Erro 502 Bad Gateway

A RFC 9110, seção 15.6.3, define o 502 como um gateway ou proxy que recebeu uma resposta inválida de um servidor interno que ele acessou para atender o pedido. Na prática, "inválida" cobre várias falhas: a conexão foi recusada, o upstream fechou antes de mandar a resposta completa, ou mandou cabeçalhos que o proxy não conseguiu interpretar ou guardar no buffer.

O servidor que devolve o 502 não é o que está com problema. O cabeçalho Server mostra quem está falando: "nginx" significa que o seu proxy reverso não recebeu uma boa resposta da aplicação, "awselb/2.0" significa que um balanceador da AWS não recebeu, e "cloudflare" significa que a CDN não conseguiu alcançar ou entender a sua origem. Corrija a camada atrás da que respondeu.

Cada proxy separa 502 de 504 de um jeito. O nginx devolve 502 quando o upstream recusa ou derruba a conexão e 504 quando o tempo se esgota. O httputil.ReverseProxy do Go devolve 502 para qualquer erro do upstream, inclusive timeout, a menos que você instale seu próprio ErrorHandler.

Se você está visitando o site

• O servidor da aplicação do site está fora do ar ou reiniciando, muitas vezes durante um deploy, enquanto o proxy ou a CDN continua de pé respondendo.
• Um pico de acessos derrubou ou esgotou o backend.
• Raramente, um proxy, VPN ou antivírus na sua própria rede que intercepta HTTPS e não consegue falar com o site.

Se você administra o servidor

• O processo da aplicação não está rodando ou escuta em outra porta ou socket: o nginx registra "connect() failed (111: Connection refused) while connecting to upstream".
• A aplicação caiu ou foi encerrada (falta de memória, promise rejeitada sem tratamento) no meio da resposta: o nginx registra "upstream prematurely closed connection while reading response header from upstream".
• Keep-alive desencontrado atrás de um balanceador: a aplicação fecha conexões ociosas antes do balanceador (o Node.js usa keepAliveTimeout de 5 segundos por padrão, um ALB da AWS usa 60 segundos de idle timeout), então o balanceador reaproveita uma conexão morta e recebe um reset.
• Cabeçalhos de resposta maiores que o buffer do proxy, geralmente cookies grandes ou cabeçalhos de autenticação longos: o nginx registra "upstream sent too big header while reading response header from upstream".
• PHP-FPM, Gunicorn ou uWSGI sem workers livres, ou o caminho do socket no nginx diferente do que o processo criou.

Se você está visitando o site

• Espere um minuto e recarregue. A maioria dos 502 é um backend reiniciando, e passa sozinho.
• Veja a página de status do site ou um serviço como o Downdetector para saber se outras pessoas também estão afetadas.
• Se só acontece com você, teste outra rede ou desligue a VPN ou o proxy por um momento.

Se você administra o servidor

• Leia primeiro o log de erros do proxy (tail /var/log/nginx/error.log); a mensagem depois do horário diz se a conexão foi recusada, derrubada ou teve cabeçalhos grandes demais.
• Chame a aplicação direto no host do proxy, sem passar pelo proxy (curl -sI http://127.0.0.1:3000/). Se falhar, o problema é a aplicação ou a porta dela, não o nginx.
• Confirme que a aplicação está rodando e é reiniciada por um supervisor (systemd, política de restart do Docker, PM2), e leia os logs dela atrás do crash ou do processo morto por falta de memória.
• Atrás de um ALB da AWS ou similar, deixe o keep-alive da aplicação maior que o idle timeout do balanceador, no Node: server.keepAliveTimeout = 65_000.
• Para cabeçalhos grandes demais, aumente proxy_buffer_size e proxy_buffers no nginx, ou diminua os cookies que a aplicação grava.

A aplicação quase nunca envia 502 por conta própria; quem gera é o proxy. Os exemplos configuram o nginx para ter menos 502 e mostram como achar qual salto falhou. Só um gateway escrito por você deve responder 502 quando o upstream falha.

upstream app {
  server 127.0.0.1:3000 max_fails=3 fail_timeout=30s;
  keepalive 32;
}

server {
  location / {
    proxy_pass http://app;
    proxy_http_version 1.1;
    proxy_set_header Connection "";

    # "upstream sent too big header" is answered with 502
    proxy_buffer_size 16k;
    proxy_buffers 8 16k;
  }

  # Your own page for 502, status unchanged
  error_page 502 /502.html;
}

# Which layer answered? The Server header says
curl -sI https://example.com/ | grep -iE '^(HTTP|server)'

# Is the app itself up? Call it without the proxy
curl -sI http://127.0.0.1:3000/

# What nginx saw
grep -E 'upstream|connect\(\)' /var/log/nginx/error.log | tail -n 20

502 vs 504

O 502 indica que o upstream respondeu mal ou desligou; o 504 indica que ele não respondeu antes do proxy desistir de esperar.

502 vs 500

O 500 vem da própria aplicação; o 502 vem do proxy na frente dela e significa que a aplicação nem conseguiu entregar uma resposta válida.

502 vs 503

O 503 diz que o serviço está indisponível de forma consciente, por manutenção ou sobrecarga; o 502 diz que o proxy tentou e recebeu lixo ou conexão derrubada.

502 vs 520

A Cloudflare usa 520 quando a sua origem devolve algo vazio ou inesperado, e uma página 502 própria para falhas dentro da rede da Cloudflare.

O erro 502 Bad Gateway é problema meu ou do site?

Quase sempre do site. Algo entre a porta de entrada do site (proxy ou CDN) e a aplicação falhou. As exceções são um proxy corporativo, VPN ou software de segurança na sua rede que fica no meio do tráfego HTTPS.

Quanto tempo dura um erro 502?

Se vem de deploy ou reinício, de segundos a poucos minutos. Se a aplicação caiu e nada a reinicia, dura até alguém corrigir o servidor, por isso supervisores de processo e health checks fazem diferença.

Por que tenho 502 intermitente atrás de um balanceador de carga?

A causa clássica é o keep-alive: a aplicação fecha conexões ociosas antes do balanceador, e ele manda um pedido numa conexão que já está fechando. Deixe o keep-alive da aplicação maior que o idle timeout do balanceador.

Qual a diferença entre erro 502 e 504?

Os dois vêm de um proxy. O 502 significa que o upstream mandou resposta inválida ou derrubou a conexão; o 504 significa que o upstream não respondeu a tempo. No nginx, conexão recusada é 502 e estourar o proxy_read_timeout (60 segundos por padrão) é 504.

Limpar o cache resolve o erro 502?

Raramente. A falha está no caminho do servidor, então limpar cache ou cookies do navegador não muda nada. Recarregar depois de um tempo, ou testar outra rede se só você é afetado, ajuda mais.