502 Bad Gateway: o que quebrou atrás do proxy e como encontrar

Quem devolve um 502 e por quê

A RFC 9110 define o 502 para um servidor atuando como gateway ou proxy que recebeu uma resposta inválida de um servidor de entrada que acessou tentando atender à requisição. Toda stack moderna tem pelo menos um salto assim: nginx ou Apache na frente de um servidor de aplicação, um balanceador de carga na frente de uma frota, uma CDN na frente da sua origem, ou os três.

Essa estratificação é a chave para ler um 502. O componente que respondeu está saudável o suficiente para gerar uma página de erro. O componente por trás dele não está. Então um 502 sempre divide a sua stack em uma metade funcionando e uma metade quebrada, e o seu trabalho é descobrir onde está a fronteira.

Os vizinhos dele dizem algo mais restrito. Um 504 Gateway Timeout significa que o backend estava acessível mas lento demais. Um 500 significa que o próprio backend rodou e lançou um erro. Um 502 significa que o backend deu uma resposta ruim ou nenhuma resposta. A comparação completa está na visão geral do 5xx.

Causas comuns

• O processo do backend não está rodando. Um servidor de aplicação travado, um pool de PHP-FPM parado, um contêiner que encerrou ou falhou na verificação de saúde. O proxy se conecta a uma porta que ninguém está escutando.
• O backend travou no meio da requisição. Uma morte por falta de memória ou uma falha de segmentação fecha a conexão antes de os cabeçalhos da resposta estarem completos.
• Endereço ou porta de upstream errados. Uma configuração que aponta para a porta antiga depois de uma mudança, ou para um host que não resolve mais.
• Incompatibilidade de protocolo. O proxy fala HTTP puro com uma porta esperando TLS, ou o contrário. Os bytes são não interpretáveis, então o proxy chama a resposta de inválida.
• Cabeçalhos de resposta grandes demais. Um cookie muito grande ou um cabeçalho incomumente longo excede o buffer do proxy, e a resposta é rejeitada em vez de repassada.
• Incompatibilidade de keep-alive. O proxy reutiliza uma conexão ociosa que o backend já fechou, produzindo 502s esporádicos sob carga por outro lado normal.
• Reinicializações e implantações. Qualquer janela onde o processo antigo parou e o novo ainda não está aceitando conexões.
• Todos os backends não saudáveis. Um balanceador de carga sem nenhum membro passando não tem para onde enviar a requisição.

Lendo o log do proxy, que geralmente encerra a investigação

O código de status é genérico, mas a linha do log do proxy é específica. Com o nginx, essas são as mensagens que vale a pena reconhecer:

[error] connect() failed (111: Connection refused) while connecting to upstream,
        upstream: "http://127.0.0.1:8080/"

[error] upstream prematurely closed connection while reading response header
        from upstream

[error] recv() failed (104: Connection reset by peer) while reading response
        header from upstream

[error] upstream sent too big header while reading response header from upstream

[error] no live upstreams while connecting to upstream

Cada uma aponta para um lugar diferente:

• connect() failed (111: Connection refused). Nada está escutando naquele endereço e porta. O backend está parado, vinculado a uma interface diferente, ou em uma porta diferente da que a configuração diz.
• upstream prematurely closed connection. O backend aceitou a requisição e depois morreu ou travou antes de terminar a resposta. Procure por travamentos, mortes por falta de memória ou um timeout de worker dentro da aplicação, não no nginx.
• connection reset by peer. Parecido, mas a conexão foi resetada ativamente. Muitas vezes um firewall no meio, ou um backend que fechou uma conexão do pool que o proxy ainda considerava aberta.
• upstream sent too big header. Um problema de tamanho de buffer no proxy, não uma falha no backend. A resposta é válida mas maior do que o proxy está configurado para segurar.
• no live upstreams. As verificações de saúde marcaram todo backend como fora do ar.

Como corrigir

1. Teste o backend diretamente, contornando o proxy. A partir do host do proxy, solicite o próprio endereço de upstream:

   curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8080/

   Um 200 aqui com um 502 na URL pública significa que a falha está na configuração do proxy ou na ligação entre os dois. Uma conexão recusada significa que o backend realmente está fora do ar.
2. Verifique se o backend está rodando e escutando no endereço que o proxy espera. Vincular a 127.0.0.1 quando o proxy disca um endereço de contêiner é uma causa frequente.
3. Leia o log de erro do proxy e combine a mensagem com a lista acima antes de mudar qualquer configuração.
4. Depois leia o log do backend. Um travamento, uma morte por falta de memória ou um timeout de worker no mesmo segundo confirma o caso "prematurely closed". Silêncio aponta de volta para conectividade.
5. Verifique o endereço, a porta e o esquema de upstream na configuração do proxy, especialmente depois de uma migração ou uma reconstrução de contêiner.
6. Aumente os buffers de cabeçalho do proxy se o log disser que o cabeçalho era grande demais, e separadamente descubra por que o cabeçalho cresceu.
7. Faça as implantações se sobreporem. Inicie o processo novo, espere ele passar em uma verificação de saúde, depois drene e pare o antigo. Atualizações contínuas com verificação de saúde eliminam por completo a janela de reinicialização que causa os 502s no momento da implantação.

Pegando um 502 que dura vinte segundos

502s de implantação e de loop de travamento são curtos. Um backend reinicia, dá erro por vinte segundos e se recupera, então quando alguém verifica o site está bem e não sobra nada para olhar. Uma verificação HTTP agendada rodando continuamente registra essas janelas com timestamps, o que transforma "estava meio estranho hoje de manhã por um pouco" em um padrão que você consegue correlacionar com implantações e reinicializações. Um 502 também pode vir de uma borda de CDN em vez da sua origem, então verificar a partir de várias regiões separa uma falha global de backend de um problema de borda afetando parte do seu tráfego, que é para o que serve o monitoramento de disponibilidade distribuído.