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:
| Quem | O que vê | Onde |
|---|---|---|
| Usuário do navegador | Um indicador de carregamento que para, ou nada | A própria página |
| curl | curl: (28) Operation timed out | Terminal, código de saída 28 |
| Python Requests | Exceção ReadTimeout | Saída do script |
| Operador do nginx | Status 499, muitas vezes 0 bytes | Log 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?
- 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.
- O nginx a aceita e a repassa à aplicação que está atrás dele.
- 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.
- 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.
- 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ódigo | Quem desistiu | Enviado ao cliente? | Solução típica |
|---|---|---|---|
499 | O cliente | Não, só no log | Upstream mais rápido, timeout do cliente mais longo |
408 | O servidor, esperando a requisição | Sim | O cliente precisa enviar mais rápido |
502 | O gateway recebeu uma resposta quebrada | Sim | Corrigir a aplicação que travou |
504 | O gateway esperou demais | Sim | Upstream 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:
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):
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:
- Os 499 se concentram em um valor? Se
rtmostra30.001,30.002e29.999em centenas de linhas, algum cliente tem um timeout de 30 segundos. Valores espalhados apontam para pessoas saindo da página. - 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.
- Quanto tempo o endpoint normalmente precisa? Confira o
urtnas 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.
- 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.
- Deixe o endpoint lento mais rápido: coloque o resultado em cache, crie o índice que falta, pagine uma resposta enorme.
- 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.
- 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_timeoutdo 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). - Use
proxy_ignore_client_abortsó 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. - 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):
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:
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 sO 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_abortem 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ção | O que fazer |
|---|---|
| 499 concentrados em um tempo de requisição | Encontre o cliente ou balanceador com esse timeout e alinhe-o |
| 499 espalhados em uma página lenta | Acelere esse endpoint ou transforme-o em tarefa em segundo plano |
| 499 vindos do IP do seu balanceador de carga | Suba o timeout dele acima do timeout do nginx e registre os IPs encaminhados |
| O seu script causa 499 em um site | Timeout de leitura mais longo, repetir só GET, menos concorrência |
| O trabalho precisa terminar mesmo se o cliente sair | Tarefa em segundo plano, ou proxy_ignore_client_abort nesse caminho |
| Alta repentina de 499 no Cloudflare | Compare 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.




