Erro 502 Bad Gateway: achar a causa e resolver

O que o erro significa

Um 502 é a resposta de um servidor que funciona. O servidor web da frente (nginx, Apache, um balanceador de carga ou uma CDN como o Cloudflare) recebeu o pedido, passou para a aplicação atrás dele (PHP-FPM, um processo Node.js ou Python) e não recebeu de volta nada aproveitável: conexão recusada, interrompida ou resposta ilegível. “Gateway” é o servidor da frente; “bad” é o que voltou de trás. Um 502 diz, portanto, duas coisas: na frente está tudo bem; atrás, algo está parado ou quebrado.

Causas frequentes

1. O processo da aplicação não está rodando. O PHP-FPM travou ou foi parado, o processo Node.js morreu, o container encerrou.
2. A aplicação está saturada. Todos os workers do PHP-FPM estão ocupados, a fila está cheia, as novas conexões são recusadas. Acontece muito depois de um pico de visitas ou por causa de uma consulta SQL lenta.
3. Socket ou porta errados. Depois de uma troca de versão do PHP, o nginx ainda aponta para php8.2-fpm.sock, enquanto o novo pool escuta em php8.4-fpm.sock.
4. Timeouts curtos demais. O backend responde, mas tarde demais para o servidor web. Algumas configurações mostram isso como 502; outras, como 504 Gateway Timeout.
5. O backend envia cabeçalhos grandes demais ou uma resposta inválida. Típico de frameworks que lotam os cookies; o nginx registra então “upstream sent too big header”.
6. A CDN não chega ao seu servidor. Uma página 502 com o logo do Cloudflare significa que o Cloudflare não recebeu nada do seu servidor: firewall, IP errado depois de uma migração ou servidor desligado.

Se você é visitante

Um 502 em um site que não é seu não se resolve do seu lado. Recarregue depois de um minuto; se persistir, só quem administra o site pode agir.

Se o site é seu: verifique primeiro

Está fora do ar para todo mundo? Abra o website down checker: código HTTP visto de fora, e quem respondeu, a CDN ou o servidor.

Hospedagem compartilhada ou construtor de sites? Ali um 502 é quase sempre um problema da hospedagem (um pool PHP saturado em um servidor compartilhado). Pule para a mensagem pronta, mais abaixo.

Servidor próprio: conecte por SSH e leia o que o servidor web diz.

# nginx: os últimos erros, os mais recentes embaixo
sudo tail -n 50 /var/log/nginx/error.log

# Apache (Debian/Ubuntu)
sudo tail -n 50 /var/log/apache2/error.log

Linhas típicas e o que significam:

• connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory): o PHP-FPM não está rodando, ou o caminho do socket está errado.
• connect() failed (111: Connection refused) while connecting to upstream: ninguém escuta na porta do backend.
• upstream prematurely closed connection: o backend travou enquanto respondia, muitas vezes por um erro fatal do PHP ou falta de memória.
• upstream sent too big header: aumente os buffers (veja abaixo).
• (11: Resource temporarily unavailable): todos os workers do PHP-FPM estão ocupados.

Soluções no seu servidor

1. Iniciar o serviço parado

# descobrir a versão do PHP-FPM que você usa
systemctl list-units --type=service | grep -E 'php|fpm'

systemctl status php8.3-fpm
sudo systemctl start php8.3-fpm

# aplicações Node.js ou Python sob systemd
sudo systemctl restart minha-app

Se não inicia, o motivo está em journalctl -u php8.3-fpm -n 50. Os mais frequentes: um disco cheio (df -h) e, logo depois, um erro de sintaxe em um pool (sudo php-fpm8.3 -t).

2. Corrigir o socket ou a porta

Compare o endereço ao qual o nginx se conecta com aquele em que o PHP-FPM escuta:

grep -r fastcgi_pass /etc/nginx/sites-enabled/
grep -r '^listen' /etc/php/*/fpm/pool.d/

Os dois precisam bater. Depois de cada alteração, teste antes de recarregar:

sudo nginx -t && sudo systemctl reload nginx

Com Apache e mod_proxy_fcgi, a mesma regra vale para a linha SetHandler "proxy:unix:/run/php/php8.3-fpm.sock|fcgi://localhost"; o teste é sudo apachectl configtest.

3. Dar fôlego ao PHP-FPM

Se o log de erros diz que os workers estão ocupados ou mostra server reached pm.max_children, aumente o limite no arquivo do pool (/etc/php/8.3/fpm/pool.d/www.conf):

pm = dynamic
pm.max_children = 20
pm.start_servers = 4
pm.min_spare_servers = 2
pm.max_spare_servers = 6

Cada worker consome memória (no WordPress, muitas vezes de 30 a 80 MB); confira free -m antes de aumentar o número e procure a consulta lenta ou o plugin que prende os workers.

4. Aumentar os buffers para cabeçalhos grandes

No bloco server do nginx:

fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;
proxy_buffers 8 16k;
proxy_buffer_size 32k;

5. O caso WordPress

Um 502 logo depois de atualizar um plugin ou tema: o PHP tropeça a cada pedido em um erro fatal ou na memória esgotada. Renomeie a pasta do plugin por SFTP ou SSH (wp-content/plugins/nome-do-plugin para nome-do-plugin.off) ou rode wp plugin deactivate nome-do-plugin, e recarregue. Aumente memory_limit no pool ou no php.ini se o journalctl mostra “Allowed memory size exhausted”.

6. Atrás do Cloudflare

Verifique se o servidor de origem responde diretamente: curl -I https://IP-DO-SERVIDOR -H 'Host: example.com' -k. Se responde, pode ser que o firewall bloqueie as faixas de endereços do Cloudflare, ou que o registro DNS no Cloudflare aponte para um IP antigo; o guia erro 521 e 522 do Cloudflare explica os passos.

Se o problema está na sua hospedagem

Em uma hospedagem compartilhada você não pode reiniciar o PHP-FPM. Envie isto para a sua hospedagem, com o horário e o erro exato:

Prezados, meu site example.com está devolvendo “502 Bad Gateway” desde aproximadamente 14h30 (UTC). Uma verificação externa confirma; não alterei nada do meu lado. Poderiam verificar os processos PHP e o servidor web da minha conta e me informar quando o site voltará ao ar?

Para não acontecer de novo

Um 502 é quase sempre um backend parado ou saturado, e as duas coisas aparecem antes que os visitantes percebam: um serviço PHP-FPM parado, uma memória que fica escassa, um disco que vai enchendo. O monitoramento de servidores com o agente de servidor sinaliza exatamente isso por dentro; as verificações de fora capturam o 502 assim que ele aparece.

Fora do ar? Nós resolvemos. No seu servidor ou em uma hospedagem compartilhada com acesso SSH, o Quick Fix, o reparo automático a preço fixo, reinicia o serviço parado se o teste da configuração dele passar; se a causa for mais profunda, o Deep Fix cuida do resto, em blocos de 15 minutos, 24 horas por dia, inclusive nos fins de semana; a estimativa é o valor máximo.