# 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.

> 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.

João Rizzon · 2026-10-12 · Infraestrutura web

---

## 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

```bash
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

```bash
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:

```bash
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:

- Origem responde **200**: o problema está na camada de borda ou no caminho entre ela e você. Vá para a seção de purga e de configuração da CDN.
- Origem responde **502 também**: a borda só repassou. O defeito é do backend. Vá para o log do proxy.

### O log do proxy, não o do PHP

No cPanel com NGINX como proxy reverso, a [documentação oficial](https://docs.cpanel.net/knowledge-base/nginx/nginx-troubleshooting/) 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.

```bash
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".

## 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:

- Limpar o cache de página da origem (plugin de cache do WordPress, cache de objeto, cache de página do servidor).
- Confirmar com `curl --resolve` que a origem devolve 200 e o HTML certo.
- Só então purgar a borda (CDN/WAF), de preferência por URL quando o problema é localizado.
- 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.

## 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:

- Se há uma camada de borda na frente, ela tem o próprio limite de espera. Aumentar só o proxy local não resolve: a borda continua desistindo antes.
- Timeout maior não acelera nada. Ele apenas deixa o processo terminar. Se a rota leva minutos por falta de índice no banco, o lugar certo é a consulta.
- Para tarefa que roda sozinha, troque HTTP por cron real no servidor. Nenhum timeout de proxy afeta um processo iniciado por CLI, e o problema some de vez.

## 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:

- Público só no Brasil, servidor no Brasil, e o ganho de borda é marginal.
- O site não serve estático pesado próprio (vídeo, downloads grandes).
- A camada foi herdada de outra agência e ninguém sabe quais regras estão ativas.
- O 502 reproduz na borda e não reproduz na origem, repetidamente, após purga correta.

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

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

> **** "O erro 502 não é do seu site em si: é um servidor intermediário avisando que não conseguiu resposta do servidor principal naquele momento. Já identifiquei qual das duas camadas falhou, corrigi e limpei o cache nas duas pontas. O site voltou e estou monitorando para confirmar que não repete."

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.

