Erro HTTP 499 Client Closed Request: causas e soluções

Publicado:

16 min de leitura

Acar Diveroli
Autor: Acar Diveroli
Um grande 499 entre linhas-guia; no alto à direita, uma marca azul perto de CLIENT corta a linha de CLIENT a SERVER

Um cliente escreve que o relatório mensal de vendas "fica carregando e nunca abre". Não há página de erro nem nada no log de erros da aplicação. No log de acesso (access log) do nginx, a linha dessa requisição termina com um status que você não vai encontrar em nenhum navegador: 499, zero bytes enviados e um tempo de requisição de exatamente 30 segundos. O servidor não falhou. Alguém parou de esperar.

A seguir: o que o código 499 significa e quem consegue vê-lo, as causas mais comuns, como lê-lo nos seus logs, como corrigi-lo no servidor, o que o Cloudflare e os balanceadores de carga informam e o que verificar quando o cliente que desistiu é o seu próprio script rodando por um proxy.

O que significa HTTP 499?

HTTP 499 significa que o cliente desistiu de uma requisição antes de o servidor responder. O cliente é quem abriu a conexão: um navegador, um app de celular, um script ou outro servidor, como um balanceador de carga. O código não diz nada sobre se a requisição era válida ou se a resposta estaria correta.

O nome vem do código-fonte do nginx. No arquivo que define os seus códigos de status, os desenvolvedores do nginx explicam que o HTTP não tem um código para um cliente que fecha a conexão enquanto a sua requisição está sendo processada, então criaram um próprio, NGX_HTTP_CLIENT_CLOSED_REQUEST, com o número 499. O comentário o limita a clientes que saem antes mesmo de o nginx tentar enviar o cabeçalho da resposta.

O 499 é um código de status HTTP oficial?

Não. O registro de códigos de status HTTP da IANA, a lista oficial por trás do padrão HTTP, mostra toda a faixa de 452 a 499 como não atribuída. O 499 pertence a um pequeno grupo que o nginx usa nos próprios logs, ao lado do 494 (cabeçalho da requisição grande demais), do 495 e do 496 (problemas com o certificado do cliente) e do 497 (HTTP sem criptografia enviado a uma porta HTTPS). Diferente de um código 4xx de verdade, como o 404 ou o 429, ele é uma entrada de log, não uma resposta: nenhum cliente jamais o recebe.

Quem vê um erro 499?

Só o operador do servidor, no log de acesso ou em análises construídas a partir dos logs. Cada lado guarda o próprio registro do mesmo momento:

QuemO que vêOnde
Usuário do navegadorUm indicador de carregamento que para, ou nadaA própria página
curlcurl: (28) Operation timed outTerminal, código de saída 28
Python RequestsExceção ReadTimeoutSaída do script
Operador do nginxStatus 499, muitas vezes 0 bytesLog de acesso

Reproduzimos isso na nossa máquina de testes com um pequeno servidor Node.js em 127.0.0.1 que responde a cada requisição depois de cinco segundos. O curl --max-time 2 desistiu com Operation timed out after 2007 milliseconds with 0 bytes received e o código de saída 28, que a libcurl define como timeout de operação; no mesmo instante, o servidor registrou que o cliente tinha fechado a conexão antes da resposta, o evento que o nginx registra como 499. Com --max-time 8, a mesma requisição retornou 200 depois de 5,0 segundos.

Como um 499 acontece, passo a passo?

  1. O cliente envia uma requisição e inicia o próprio cronômetro: um navegador espera enquanto o usuário esperar; um script, o quanto o timeout permitir.
  2. O nginx a aceita e a repassa à aplicação que está atrás dele.
  3. A resposta demora mais do que o cliente aceita esperar: uma consulta pesada ao banco de dados, um cache frio, uma API de terceiros lenta.
  4. O cliente fecha a conexão. O usuário vai para outra página, o timeout do script dispara ou um balanceador de carga na frente corta a requisição.
  5. O nginx percebe a conexão fechada, por padrão também fecha a própria conexão com a aplicação e registra a requisição com o status 499.

Se a aplicação para no passo 5 depende da aplicação. Muitos frameworks só percebem a conexão fechada quando tentam escrever a resposta, então a consulta cara pode continuar até o fim, e o resultado é jogado fora.

O que causa o HTTP 499?

Quase todo 499 é um descompasso de timeouts ou uma pessoa que parou de esperar. Verifique estas causas mais ou menos nesta ordem:

  • Um timeout do cliente menor que o tempo de resposta do servidor. Um app que espera 10 segundos por um endpoint que precisa de 12 produz um fluxo constante de 499.
  • Pessoas saindo da página: fecham uma aba, clicam em Parar ou clicam em outro lugar antes de a página carregar.
  • Um balanceador de carga, uma CDN ou um proxy na frente do nginx com um timeout menor. O nginx então registra o endereço dessa camada intermediária como cliente.
  • Redes móveis. Um celular que passa do Wi-Fi para os dados móveis derruba a conexão no meio da requisição.
  • Verificações de integridade (health checks) e monitores que esperam dois segundos por uma página que leva três.
  • Scripts e crawlers com timeouts agressivos, incluindo as suas próprias tarefas por um proxy.
  • Cancelamento pelo próprio app. Uma caixa de busca cancela a requisição anterior quando o usuário digita a próxima letra.

Qual a diferença entre 499, 408, 502 e 504?

A diferença está em quem desistiu e se uma resposta foi enviada. O 499 é o único deste grupo que ninguém recebe:

CódigoQuem desistiuEnviado ao cliente?Solução típica
499O clienteNão, só no logUpstream mais rápido, timeout do cliente mais longo
408O servidor, esperando a requisiçãoSimO cliente precisa enviar mais rápido
502O gateway recebeu uma resposta quebradaSimCorrigir a aplicação que travou
504O gateway esperou demaisSimUpstream mais rápido, timeout do gateway mais longo

Um 499 e um 504 muitas vezes têm a mesma causa de fundo, um upstream lento: se o cronômetro do cliente acaba primeiro, você vê um 499; se o do nginx acaba antes, o cliente recebe um 504. Uma resposta quebrada da aplicação é um 502, tratado em Erro 502 Bad Gateway: o que significa e como resolver.

Como ler o 499 nos logs do nginx?

Adicione campos de tempo ao log de acesso e depois veja quanto o cliente esperou antes de cada 499. O formato combined padrão do nginx registra o status, mas não o tempo, então comece com um formato próprio:

nginx
log_format timed '$remote_addr - [$time_local] "$request" $status $body_bytes_sent '
                 'rt=$request_time urt=$upstream_response_time us=$upstream_status '
                 '"$http_user_agent"';
access_log /var/log/nginx/access.log timed;

$request_time é o tempo entre o primeiro byte que o nginx leu do cliente e o momento em que ele escreveu a linha do log, em segundos com resolução de milissegundos. $upstream_response_time é o tempo gasto recebendo a resposta da aplicação, e $upstream_status é o status que a aplicação retornou. Uma linha 499 nesse formato poderia ficar assim (valores de exemplo):

text
203.0.113.7 - [19/Nov/2026:10:42:13 +0000] "GET /reports/monthly HTTP/1.1" 499 0 rt=30.001 urt=30.000 us=- "ExampleApp/2.1"

Três leituras respondem à maioria das perguntas:

  1. Os 499 se concentram em um valor? Se rt mostra 30.001, 30.002 e 29.999 em centenas de linhas, algum cliente tem um timeout de 30 segundos. Valores espalhados apontam para pessoas saindo da página.
  2. Quem é o cliente? O endereço e o user agent distinguem um navegador de um app de celular, do seu balanceador de carga ou de um serviço de monitoramento.
  3. Quanto tempo o endpoint normalmente precisa? Confira o urt nas requisições bem-sucedidas para a mesma URL. Se elas muitas vezes demoram mais que o valor concentrado dos 499, o endpoint é lento demais para esse cliente. Na linha do 499, us=- significa que a aplicação ainda não tinha enviado um status.

Atrás de um balanceador de carga, $remote_addr é o endereço do balanceador em todas as linhas; registre também o endereço encaminhado do cliente, senão todo 499 vai parecer vir de uma única máquina.

Como corrigir o HTTP 499 no servidor?

Corrija primeiro a requisição lenta e depois os timeouts; um timeout mais longo só transfere a espera para outro lugar.

  1. Descubra quem fechou a conexão com os campos de log acima. Um valor concentrado vindo do seu balanceador de carga se resolve na configuração; valores espalhados vindos de navegadores são um problema de velocidade.
  2. Deixe o endpoint lento mais rápido: coloque o resultado em cache, crie o índice que falta, pagine uma resposta enorme.
  3. Transforme trabalhos longos em tarefas em segundo plano. Responda na hora com um ID de tarefa (o status 202 Accepted existe para isso) e deixe o cliente consultar de novo quando o relatório estiver pronto.
  4. Alinhe os timeouts de fora para dentro. Cada camada deve esperar um pouco mais que a que está atrás dela: o cliente, depois a CDN ou o balanceador de carga, depois o nginx, depois a aplicação. O proxy_read_timeout do nginx é a espera entre duas leituras da aplicação, não um limite para a resposta inteira, e o padrão é 60 segundos (módulo proxy do nginx).
  5. Use proxy_ignore_client_abort só com um motivo. Desligada por padrão, essa diretiva decide se o nginx fecha a conexão com a aplicação quando o cliente sai. Ligá-la deixa terminar o trabalho que precisa ser concluído, como preencher um cache, mas aí cada requisição abandonada custa o tempo inteiro de servidor.
  6. Mantenha o 499 visível, mas separado, no monitoramento. Alguns 499 são normais em qualquer site movimentado; uma alta repentina em uma URL é um sinal precoce de que ela ficou lenta.

O que significa o 499 no Cloudflare e nos balanceadores de carga?

No Cloudflare, o 499 significa a mesma coisa: o cliente fechou a conexão antes de a requisição terminar. A documentação do Cloudflare sobre o erro 499 afirma que nenhuma resposta 499 é enviada ao cliente e que o código aparece só nos logs. Ela aponta como causas prazos curtos do cliente, servidores de origem lentos e quedas na taxa de acerto do cache, e sugere comparar a taxa de 499 com todas as requisições ao mesmo endpoint. Desde 19 de janeiro de 2026, o Cloudflare também registra requisições HTTP/3 canceladas como 499, então os sites podem ver mais deles no tráfego HTTP/3.

Outros balanceadores de carga usam números próprios para o mesmo evento. O Application Load Balancer da AWS registra HTTP 460 quando o cliente fecha a conexão antes de o timeout de inatividade (idle timeout) do balanceador terminar, e o guia de solução de problemas dele dá o mesmo conselho: responder antes do timeout do cliente ou aumentar o timeout do cliente na mesma medida.

Quando o cliente é você: 499 causado pelo seu próprio script

Se o operador de um site disser que as suas requisições aparecem como 499, o seu script desligou antes de o servidor dele responder. A correção fica no seu código.

As bibliotecas HTTP costumam dividir o timeout em dois: o timeout de conexão limita quanto tempo o script espera para abrir a conexão, e o timeout de leitura, quanto tempo ele espera por dados depois que a requisição sai. A biblioteca Requests do Python não define nenhum dos dois a menos que você defina, então um script pode ficar travado por minutos, enquanto um timeout de leitura muito curto deixa um 499 em cada página lenta.

O exemplo abaixo espera mais a cada tentativa, em vez de desligar de novo no mesmo ponto. Nós o rodamos contra o mesmo servidor de testes local (Python 3.13, Requests 2.34):

python
import time

import requests

URL = "http://127.0.0.1:18499/report"  # nosso servidor de testes local; ele responde depois de 5 segundos
PROXIES = None  # ou {"http": "http://user:pass@pr.proxynet.io:8000", "https": "http://user:pass@pr.proxynet.io:8000"}
CONNECT = 5  # segundos para abrir a conexão
READ_TIMEOUTS = (2, 4, 8)  # cada nova tentativa espera mais, em vez de desligar no mesmo ponto


def fetch(url):
    for attempt, read in enumerate(READ_TIMEOUTS, start=1):
        started = time.monotonic()
        try:
            r = requests.get(url, proxies=PROXIES, timeout=(CONNECT, read))
            print(f"attempt {attempt}: HTTP {r.status_code} after {time.monotonic() - started:.1f} s")
            return r
        except requests.exceptions.ReadTimeout:
            # Aqui nós desligamos; um servidor com nginx registra esta requisição como 499.
            print(f"attempt {attempt}: no answer within {read} s, closed the connection")
        except requests.exceptions.ConnectTimeout:
            print(f"attempt {attempt}: could not connect within {CONNECT} s")
        time.sleep(1)
    raise RuntimeError(f"{url}: no answer within {READ_TIMEOUTS[-1]} s, check the server side")


fetch(URL)

Saída:

text
attempt 1: no answer within 2 s, closed the connection
attempt 2: no answer within 4 s, closed the connection
attempt 3: HTTP 200 after 5.0 s

O servidor registrou as duas primeiras tentativas como fechadas pelo cliente depois de 2,0 e 4,0 segundos, e a terceira como um 200 normal. Repita assim só requisições que não mudam nada, como GET: um POST que deu timeout pode ter sido processado mesmo assim. Se uma página está lenta para todo mundo, reduza o seu ritmo de requisições. Como um crawler deve tratar os outros códigos que encontra está em Códigos de status HTTP no web scraping: 403, 407, 429, 503.

Um proxy causa erros 499?

Um proxy não cria 499, mas acrescenta um tempo que o seu timeout precisa cobrir: cada requisição vai até o proxy e de lá até o destino, e uma saída longe do destino alonga cada ida e volta. Um timeout de leitura ajustado para requisições diretas pode ficar curto, e o destino então registra um 499 com o endereço de saída do proxy como cliente.

Meça antes de mudar qualquer coisa: curl -w com %{time_connect} e %{time_starttransfer} mostra quanto tempo levam a conexão e o primeiro byte, com e sem o proxy. Defina o timeout a partir desses números, com folga para páginas lentas. Para trabalhos longos contra poucos sites conhecidos, os Proxies de datacenter dão a você um endereço de saída fixo em um data center perto do destino, então o tempo adicional fica pequeno e estável.

Para rastreamentos grandes, a nossa configuração de web crawler inclui uma espera ajustável entre requisições, o que mantém a sua carga sobre o destino baixa o bastante para que as páginas dele nem cheguem a ficar lentas.

Onde você encontra o HTTP 499

  • Um log de acesso do nginx com linhas 499 concentradas em um mesmo tempo de requisição.
  • Uma exportação de logs do Cloudflare com 499 ao lado de um servidor de origem lento.
  • Uma API cujos clientes móveis geram 499 no trajeto para o trabalho.
  • Um crawler ou uma tarefa de dados cujo timeout de leitura é menor que o tempo de resposta do destino.

Erros comuns

  • Tratar o 499 como erro do servidor. Contar os 499 junto com os erros 5xx faz você procurar falhas que não existem.
  • Aumentar todo timeout para vários minutos. Os 499 somem, mas as requisições lentas agora prendem conexões e workers por minutos, e o usuário continua esperando.
  • Ligar proxy_ignore_client_abort em todo lugar. Uma leva de clientes impacientes vira uma leva de trabalho a custo cheio.
  • Repetir às cegas um POST que deu timeout. A primeira tentativa pode ter dado certo, e a repetição cria um pedido ou registro duplicado.
  • Manter o mesmo timeout curto ao passar por um proxy. O salto extra precisa de folga; meça-o primeiro.

Guia de decisão

SituaçãoO que fazer
499 concentrados em um tempo de requisiçãoEncontre o cliente ou balanceador com esse timeout e alinhe-o
499 espalhados em uma página lentaAcelere esse endpoint ou transforme-o em tarefa em segundo plano
499 vindos do IP do seu balanceador de cargaSuba o timeout dele acima do timeout do nginx e registre os IPs encaminhados
O seu script causa 499 em um siteTimeout de leitura mais longo, repetir só GET, menos concorrência
O trabalho precisa terminar mesmo se o cliente sairTarefa em segundo plano, ou proxy_ignore_client_abort nesse caminho
Alta repentina de 499 no CloudflareCompare com todas as requisições, verifique o tempo da origem e o cache

Perguntas frequentes

O HTTP 499 é um erro do cliente ou do servidor?

É registrado como um evento do lado do cliente: o cliente fechou a conexão antes da resposta. Mesmo assim, a causa pode estar no servidor, porque foi uma resposta lenta que fez o cliente desistir.

Um usuário pode ver uma página de erro 499?

Não. Nada é enviado ao cliente, então um navegador nunca mostra "499". O usuário vê uma página que parou de carregar ou a própria mensagem de timeout do navegador.

O que significa 499 no nginx?

É o código próprio do nginx para "Client Closed Request": o cliente fechou a conexão antes de o nginx enviar o cabeçalho da resposta. O nginx o define porque o padrão HTTP não tem um código para esse caso.

O que significa HTTP 499 no Cloudflare?

O mesmo: o cliente fechou a conexão antes de o Cloudflare terminar a requisição. Ele aparece só em logs e análises, na maioria das vezes por timeouts do cliente, servidores de origem lentos ou falhas de cache.

Um 499 significa que o servidor parou de processar a requisição?

Não necessariamente. Por padrão o nginx fecha a conexão com a aplicação, mas a aplicação pode continuar trabalhando até tentar enviar a resposta, então um POST que deu timeout pode ter sido concluído.

Como corrigir um 499 por timeout?

Descubra quem fechou a conexão pelo tempo de requisição e pelo endereço do cliente no log, acelere o trabalho lento ou passe-o para uma tarefa em segundo plano e, depois, faça cada timeout ser mais longo que o da camada atrás dele.

Em resumo

O HTTP 499 é a entrada de log do nginx para um cliente que fechou a conexão antes de o servidor responder; não é um código de status oficial e nunca chega ao cliente. Tempos de requisição concentrados apontam para um timeout em algum ponto da cadeia; os espalhados, para páginas lentas e usuários impacientes. Corrija o endpoint lento, tire o trabalho longo de dentro da requisição e alinhe os timeouts do cliente para dentro. Quando o cliente é o seu próprio script, dê a ele um timeout de leitura que cubra o destino e qualquer salto por proxy, repita só requisições seguras e compare os nossos tipos de proxy se precisar de uma saída mais estável.