502 Bad Gateway

O que este erro significa e como reconhecê-lo

• O navegador exibe 502 Bad Gateway ou Bad Gateway, às vezes com a identidade visual do Nginx, Apache, Cloudflare ou de outro proxy.
• O erro afeta vários usuários, começa após um deploy ou alteração de configuração, ou aparece durante um aumento de tráfego.
• As falhas podem ser intermitentes quando workers de backend, memória, CPU ou conexões de banco de dados se esgotam.
• O log do proxy informa falha na conexão upstream, timeout, linha de status ilegível, resposta malformada, cabeçalhos grandes demais ou erro de socket.
• Uma requisição direta à origem funciona, enquanto a mesma requisição por uma CDN retorna 502, indicando problemas de acesso da CDN à origem, firewall, TLS ou roteamento.

Causas principais, por probabilidade

1. Backend parado ou em falha: PHP-FPM, Node.js, Gunicorn ou outro processo da aplicação parou, está em um loop de falhas ou não iniciou após o deploy.
2. Sobrecarga ou timeout do backend: workers, memória, CPU, conexões de banco de dados ou outra dependência estão esgotados, impedindo que o proxy obtenha uma resposta a tempo.
3. Configuração upstream incorreta: o proxy aponta para o host, a porta, o endereço do container, o Unix socket ou o caminho da aplicação incorreto.
4. Falha de acesso ao socket ou ao firewall interno: o proxy não consegue alcançar o backend por causa de permissões do socket, política de rede, firewall ou alteração em security group.
5. Resposta do backend inválida ou grande demais: a aplicação envia uma saída malformada, uma linha de status inutilizável ou cabeçalhos maiores do que o proxy consegue aceitar.
6. Falha entre a CDN e a origem: uma CDN não consegue alcançar a origem, está bloqueada pelo firewall da origem ou não consegue estabelecer a conexão HTTPS esperada pela configuração da origem.

Como corrigir

1. Identifique onde o 502 é gerado

Verifique se a página de erro identifica o Nginx, o Apache, a Cloudflare, uma plataforma de hospedagem ou outro intermediário. Determine se todas as rotas falham ou apenas um caminho da aplicação e registre o horário da falha e a URL afetada. Isso ajuda a associar a requisição aos logs corretos.

2. Verifique o processo de backend e seus logs

Com acesso autorizado ao servidor ou ao painel de hospedagem, verifique se o processo da aplicação está em execução e aceitando requisições. Analise os logs em busca de loops de falha, erros fatais da aplicação, encerramento por falta de memória, dependências ausentes ou falhas de inicialização.

Por exemplo, uma verificação de serviço somente para leitura pode ser:

systemctl status php8.2-fpm
systemctl status nginx
pm2 status

Use a versão instalada do PHP-FPM e o gerenciador de processos correspondente, em vez de copiar esses nomes sem alterações. Se o backend estiver parado ou em um loop de falhas, corrija primeiro a causa subjacente. Só então considere reiniciar o serviço afetado por meio do procedimento normal de mudança; uma reinicialização pode interromper requisições e remover um contexto de execução útil. Portanto, confirme a autorização e capture os logs relevantes antes disso.

3. Leia o error log do proxy

Associe o horário do log a uma requisição com falha. No Nginx, consulte o error log configurado, geralmente /var/log/nginx/error.log. No Apache usando mod_proxy ou mod_proxy_fcgi, consulte o error log do Apache.

Algumas distinções úteis incluem:

• connect() failed: o proxy não consegue alcançar o upstream configurado.
• upstream timed out: o backend ou uma de suas dependências está lento demais ou sobrecarregado.
• upstream sent too big header: os cabeçalhos da resposta excedem os buffers configurados do proxy.
• Um erro ao ler a linha de status: o backend fechou a conexão ou retornou uma resposta inválida.

O local exato do log e o formato das mensagens dependem do servidor e da plataforma de hospedagem.

4. Verifique o host, a porta ou o socket upstream

Revise a configuração do reverse proxy. No Nginx, verifique o bloco proxy_pass ou upstream. No Apache, verifique ProxyPass, ProxyPassMatch e as configurações de conexão do PHP-FPM.

Use uma verificação somente para leitura dos listeners e uma requisição local, quando apropriado:

ss -tlnp
curl http://127.0.0.1:PORT

Substitua PORT pela porta configurada da aplicação. Se a aplicação usar um Unix socket, verifique se o caminho existe e se o processo do proxy consegue acessá-lo. No PHP-FPM, a configuração listen do pool precisa corresponder ao endereço ou socket configurado no Apache ou no Nginx. Não exponha publicamente um endpoint interno de teste apenas para realizar esta verificação.

5. Investigue sobrecarga, dependências e timeouts

Se o backend estiver em execução, mas as falhas coincidirem com picos de tráfego ou requisições lentas, verifique CPU, memória, quantidade de workers, conexões de banco de dados, profundidade da fila e limites de recursos do painel de hospedagem. Um processo pode estar em execução sem conseguir aceitar trabalho adicional.

Não aumente timeouts do proxy ou tamanhos de buffer sem evidências. Se o log identificar cabeçalhos grandes demais, inspecione a resposta da aplicação e revise as configurações proxy_buffer_size e proxy_buffers relevantes do Nginx. Se for necessária uma alteração de configuração, valide-a e aplique-a por meio do procedimento de mudança aprovado, em vez de recarregar um proxy de produção sem autorização.

6. Compare a origem com o caminho da CDN

Quando a Cloudflare ou outra CDN estiver na frente do site, teste a origem diretamente usando o endereço correto da origem e o cabeçalho Host, com autorização para isso. Compare o resultado com a requisição pública.

• A origem também falha: investigue a aplicação, o proxy, o socket, a porta, o firewall e as condições de recursos na origem.
• A origem funciona, mas a CDN falha: verifique as regras de firewall entre a CDN e a origem, a acessibilidade da origem, o roteamento e o modo de SSL/TLS da origem configurado na CDN. Confirme se a origem apresenta o protocolo e a configuração de certificado esperados pela CDN.

7. Faça um novo teste após corrigir a causa

Primeiro, confirme que a origem retorna a resposta esperada. Depois, teste a requisição por meio do reverse proxy ou da CDN. Se apenas algumas URLs falharem, compare as rotas da aplicação, o tamanho da resposta, os requisitos de autenticação e as dependências do backend, em vez de tratar o problema como uma indisponibilidade geral.

8. Verifique os limites do painel de hospedagem

No cPanel, Plesk ou em uma hospedagem compartilhada semelhante, revise os logs do PHP-FPM e de uso de recursos. A conta pode estar atingindo um limite de processos, memória ou concorrência imposto pelo provedor. Se o limite não puder ser alterado, informe ao host os horários das falhas, a rota afetada e a mensagem de log relevante para que ele possa consultar os registros da infraestrutura.

Prevenção e como verificar a correção

• Execute a aplicação sob supervisão de processos e monitore falhas repetidas, em vez de depender apenas de reinicializações automáticas.
• Monitore memória, CPU, uso de workers, conexões de banco de dados, profundidade da fila e limites do painel de hospedagem antes que afetem as requisições.
• Defina timeouts deliberados e compatíveis entre a aplicação, o proxy, o load balancer e a CDN; não use timeouts mais longos para ocultar um backend com problemas.
• Verifique a porta ou o socket esperado da aplicação após deploys e alterações de configuração.
• Teste rotas representativas diretamente na origem e por meio da CDN após alterações no TLS da origem, nas regras de firewall ou na configuração do proxy.
• Mantenha logs do proxy e da aplicação com horários sincronizados para que respostas 502 intermitentes possam ser associadas a eventos do backend.
• Documente o serviço responsável, o endereço upstream, as permissões do socket e o procedimento de recuperação aprovado para o ambiente.

Perguntas frequentes