blog
Infraestrutura web

Erro 502 Bad Gateway: 3 comandos para achar a camada que falhou

Separar quem devolveu o erro de quem simplesmente não respondeu muda a correção inteira. O roteiro abaixo serve para qualquer site da sua carteira.

JR · · 9 min de leitura · 1 tabela · 4 blocos de código

Resposta curta: 502 Bad Gateway é sempre um servidor intermediário avisando que não recebeu resposta válida do servidor de trás. A triagem cabe em três passos: ler o cabeçalho `Server` da resposta, testar a origem direto com `curl --resolve` e abrir o `error.log` do NGINX para ver o motivo literal da falha de upstream.

Neste artigo
  1. O que o 502 diz e o que ele não diz
  2. Três comandos que separam borda de origem
  3. Como ler a linha de upstream no error.log
  4. Purgar a origem antes da borda, nunca o contrário
  5. 504 de processo longo: ajustar a espera ou trocar HTTP por cron
  6. Quando desligar a CDN é a resposta certa
  7. Checklist reutilizável e a frase para o cliente

O que o 502 diz e o que ele não diz

502 Bad Gateway significa uma coisa só: um servidor que atuava como intermediário pediu a resposta para outro servidor e recebeu algo inválido ou não recebeu nada. Quem escreve a mensagem na tela é o intermediário, nunca a origem. É por isso que o texto do erro varia tanto: a página branca com letra Times é do NGINX, a tela com o número do datacenter e o código 502 é da Cloudflare, o bloco colorido com o nome do site é do painel de hospedagem.

Isso muda a triagem inteira. Com 500 você vai direto ao log de erro do PHP. Com 502 você não sabe nem qual máquina reclamou. Pode ter sido a borda (CDN/WAF) falando com o servidor de origem, ou o proxy local falando com o backend PHP, ou os dois em cascata.

O 504 Gateway Timeout é o primo do 502 e muda o diagnóstico: ali o intermediário esperou e desistiu dentro de um tempo definido. 502 costuma ser conexão recusada, resposta malformada ou processo que morreu no meio. 504 é quase sempre processo longo demais.

Três comandos que separam borda de origem

A ordem importa. Cada comando elimina uma camada.

Ler o cabeçalho Server para saber quem respondeu

curl -sS -I https://exemplo.com.br/

Leia três cabeçalhos: Server, Via e qualquer CF-Ray, X-Cache ou similar. Se Server: cloudflare aparece junto do 502, a borda está falando. Se o cabeçalho é Server: nginx sem marca de CDN, o 502 nasceu dentro da hospedagem.

Anote também Content-Length. Página de erro de borda costuma ser bem maior que a página de erro padrão de um proxy local, porque traz HTML de marca.

Falar direto com a origem pulando a borda com curl --resolve

curl -sS -I https://exemplo.com.br/ --resolve exemplo.com.br:443:203.0.113.10

Substitua pelo IP real do servidor de hospedagem (o endereço do exemplo é fictício, reservado para documentação).

Um aviso antes de interpretar o resultado: quando o certificado válido vive na borda, a origem costuma apresentar um certificado próprio, autoassinado ou de outro domínio. O curl aborta com erro de verificação de TLS, e isso não significa que o site caiu. Leia o erro: se for SSL certificate problem ou certificate subject name does not match, repita com -k para ignorar a validação, ou fale em HTTP forçando o cabeçalho de host:

curl -sS -I -k https://exemplo.com.br/ --resolve exemplo.com.br:443:203.0.113.10
curl -sS -I http://203.0.113.10/ -H 'Host: exemplo.com.br'

O status que vier dessas duas chamadas é o que vale para a triagem. Erro de conexão recusada ou timeout é outra história: aí a origem está mesmo indisponível.

Duas leituras possíveis:

O log do proxy, não o do PHP

No cPanel com NGINX como proxy reverso, a documentação oficial aponta os arquivos de erro do NGINX em /var/log/nginx/ como o primeiro lugar a olhar quando o serviço devolve erro. É ali que aparece o motivo literal da falha de upstream.

tail -n 50 /var/log/nginx/error.log

Se você não tem shell como root, peça ao suporte exatamente isto: as últimas linhas do error.log do NGINX no horário do erro. É um pedido específico e verificável, muito melhor que "o site está dando 502".

Triagem de 502: da borda até o backendCabeçalho ServerQuem escreveu a página de erroTeste na origemcurl --resolve no IP realOrigem responde 200Culpa da borda: CDN ou WAFOrigem responde 502Culpa do backend: ler error.logTrecho de upstreamRecusado, morto ou timeout
Cada passo elimina uma camada antes do próximo.

Como ler a linha de upstream no error.log

O que interessa na linha de erro é o trecho depois de upstream. Ele nomeia a causa em uma expressão curta.

Trecho no log O que aconteceu Primeira ação
connect() failed (111: Connection refused) O backend não estava escutando na porta/socket Verificar se o serviço PHP/Apache subiu
no live upstreams Todos os destinos do pool foram marcados como indisponíveis Reiniciar o backend e revisar o pool
upstream prematurely closed connection O processo morreu no meio da resposta Memória, OOM killer ou fatal do PHP
upstream timed out O backend demorou mais que o limite Ajuste de timeout e investigação de lentidão
recv() failed (104: Connection reset by peer) Conexão cortada pelo outro lado Mesma trilha de processo que morre

As três primeiras linhas quase sempre viram 502. A quarta vira 504. O tratamento é diferente e misturar os dois é o erro mais comum de triagem.

Quando o motivo é processo que morre, o próximo arquivo é o log de erro do PHP do site, não mais o do proxy. O proxy já disse tudo o que sabia.

Purgar a origem antes da borda, nunca o contrário

Depois de corrigir, muita gente limpa a CDN primeiro e vê o erro voltar em segundos. Faz sentido: se a origem ainda serve a resposta ruim, a borda só busca de novo a resposta ruim e volta a guardá-la.

A ordem que funciona:

  1. Limpar o cache de página da origem (plugin de cache do WordPress, cache de objeto, cache de página do servidor).
  2. Confirmar com curl --resolve que a origem devolve 200 e o HTML certo.
  3. Só então purgar a borda (CDN/WAF), de preferência por URL quando o problema é localizado.
  4. Revalidar sem cache local: curl -sS -I https://exemplo.com.br/ e conferir que o status é 200 e o cabeçalho de cache indica resposta nova.

Purgar tudo na borda em site grande sai caro: o cache fica frio e cada URL volta a bater na origem até reaquecer. Quanto tempo isso dura depende do tráfego e do tamanho do catálogo, e não dá para cravar. Em incidente de 502 numa rota específica, purgue a rota.

Ordem de purga que evita o erro voltarLimpar cache da origemPlugin, objeto e páginaValidar com --resolveOrigem devolve 200 e HTML certoPurgar a bordaPor URL quando o erro é localizadoRevalidar sem cacheConferir status e cabeçalho de cache
Purgar a borda antes da origem recoloca a resposta ruim em cache.

504 de processo longo: ajustar a espera ou trocar HTTP por cron

Importação de produtos, backup via painel, relatório pesado, cron chamado por HTTP. Tudo isso extrapola o limite de espera do proxy e devolve 504 mesmo com o site saudável.

O ajuste correto é no tempo que o intermediário aguarda a resposta do backend. Em NGINX, a diretiva é proxy_read_timeout. Em cPanel, não edite diretamente o arquivo gerado pelo painel: configuração de NGINX administrada por painel é reconstruída quando o serviço é regerado, e a edição manual se perde. Use o mecanismo de inclusão previsto pelo painel (os diretórios de include destinados a customização) ou peça ao provedor que aplique a mudança no lugar certo.

Três ressalvas que valem mais que o ajuste:

Quando desligar a CDN é a resposta certa

Vale dizer contra o interesse de quem vende infraestrutura: nem todo site precisa de CDN, WAF ou proxy extra. Critérios objetivos para desligar a camada em vez de depurá-la:

Desligar a camada por uma janela curta de observação, 30 minutos bastam na maioria dos casos, é um teste legítimo, desde que feito na ordem certa. O caminho mais rápido e reversível é a própria CDN: pausar o serviço ou mudar o registro para modo somente DNS, o que passa a valer em segundos e dispensa mexer no TTL. Se não houver esse controle e você precisar apontar o DNS direto para a origem, reduza o TTL do registro antes e espere o TTL antigo expirar, porque enquanto os resolvedores servirem o valor em cache a troca não produz efeito nenhum. Só depois disso a janela de observação faz sentido.

Antes de tirar a borda, confirme que a origem tem certificado válido para o domínio. Se o HTTPS do site vive na borda, remover a camada deixa o visitante com erro de certificado, que é um estrago maior que o 502. Emita ou valide o certificado na origem primeiro.

Feito isso, confirme o status com curl e observe. Se o erro some, você achou a camada culpada e decide com dado, não com palpite. Se o erro continua, a camada está inocente e você economizou horas.

Quando a camada fica, documente no mesmo lugar em que você guarda credenciais: quem é o provedor de borda, qual IP é a origem real e onde se faz a purga. Metade do tempo perdido em incidente de 502 é procurar isso.

Checklist reutilizável e a frase para o cliente

Triagem de 502 em oito passos

  1. Reproduzir com curl -sS -I e anotar o status e o cabeçalho Server.
  2. Verificar se o 502 é do site inteiro ou de uma rota (teste a home e a URL reclamada).
  3. Testar a origem com --resolve no IP real.
  4. Se a origem está boa: investigar borda, regras de WAF e purga.
  5. Se a origem está ruim: ler error.log do NGINX e classificar o trecho de upstream pela tabela acima.
  6. Conexão recusada ou pool vazio: confirmar que o backend subiu.
  7. Timeout: separar processo longo legítimo (ajuste de espera ou migração para cron) de lentidão real (consulta, plugin).
  8. Corrigir, purgar origem, validar, purgar borda, validar de novo.

As seis informações que padronizam a triagem em vários sites

Guarde para cada cliente, em uma planilha ou no gerenciador de senhas da agência: domínio, IP de origem, se há borda e qual, caminho do log de erro do site, nome do plugin de cache e endpoint de purga. Com essas seis informações, a triagem acima roda em poucos minutos em qualquer site da carteira, inclusive por alguém da equipe que nunca entrou naquele projeto.

Para site com rotina pesada conhecida (ERP, importação, sincronização), registre junto o horário da tarefa. 502 e 504 que aparecem sempre na mesma faixa de horário raramente são coincidência.

A frase pronta para explicar o 502 ao cliente

Quando o cliente perguntar o que houve, sem jargão e sem culpar ninguém antes da hora:

Se ainda estiver investigando, troque a segunda frase por: "Estou isolando qual das duas camadas falhou e te atualizo em seguida." Cliente aceita bem um prazo. Não aceita bem silêncio.

Referências

  1. Documentação oficial (cpanel) — NGINX Troubleshooting. Consultado em 2026-10-09.
Leia também