Erro 502 Bad Gateway, 503 ou 504 no Nginx? Veja o que cada código significa e como achar a causa nos logs do PHP-FPM, do banco e do sistema.

Para que serve

O erro 502 Bad Gateway e os erros 503 e 504 aparecem quando o servidor web (Nginx, Apache ou um proxy como a Cloudflare) não consegue obter resposta da aplicação que está atrás dele. Eles quase nunca são problema de rede ou de hardware: em geral, o PHP-FPM, o banco ou a aplicação parou, ficou lento ou está sem recursos. Este guia mostra como descobrir qual é o caso.

O que cada código significa

CódigoSignificadoCausa mais comum
502 Bad GatewayO proxy recebeu resposta inválida ou a conexão foi recusadaPHP-FPM ou aplicação parada, socket errado, processo morto por falta de memória
503 Service UnavailableServiço indisponível temporariamenteModo de manutenção, limite de requisições (limit_req), todos os processos ocupados, backend marcado como fora
504 Gateway TimeoutO proxy esperou e a resposta não veio a tempoScript lento, consulta pesada no banco, chamada externa travada, timeout curto demais

Se a página de erro tem a marca da Cloudflare, observe também se o problema aponta para o "Host" (seu servidor) ou para a própria Cloudflare. Os códigos 520 a 526 são exclusivos dela; o 524, por exemplo, indica que seu servidor levou mais de 100 segundos para responder.

Pré-requisitos

  • Acesso SSH ao servidor ou à VM do site. Se o SSH também não responder, entre pelo console IPMI/iLO: provavelmente o problema é falta de memória ou de disco.

Passo a passo para diagnosticar o erro 502 Bad Gateway, o 503 e o 504

1. Leia o log de erro do servidor web

Ele quase sempre diz exatamente o que aconteceu:

tail -n 50 /var/log/nginx/error.log      # ou o error_log definido no server block
tail -n 50 /var/log/apache2/error.log

Mensagens típicas e o que fazer:

  • connect() to unix:/run/php/... failed (2: No such file or directory): o PHP-FPM está parado ou o caminho do socket está errado.
  • connect() ... failed (13: Permission denied): o usuário do Nginx não tem acesso ao socket. Confira listen.owner/listen.group no pool.
  • connect() failed (111: Connection refused) while connecting to upstream: a aplicação de destino (Node, VM interna) não está escutando na porta.
  • upstream timed out (110: Connection timed out) while reading response header: a aplicação demorou mais que o fastcgi_read_timeout ou proxy_read_timeout (padrão de 60 s). É o 504.
  • upstream prematurely closed connection: o processo morreu no meio da requisição (erro fatal, falta de memória, request_terminate_timeout).
  • limiting requests, excess: o 503 veio de uma regra limit_req sua.

2. Verifique os serviços

systemctl status nginx php8.4-fpm mariadb --no-pager
ls -l /run/php/

Se algum estiver parado, veja o motivo antes de reiniciar: journalctl -u php8.4-fpm -n 50 --no-pager.

3. Confira o log do PHP-FPM

tail -n 50 /var/log/php8.4-fpm.log
  • server reached pm.max_children setting: todos os processos ocupados; novas requisições esperam e acabam em 502 ou 504. Aumente pm.max_children se houver memória, ou descubra o que está prendendo os processos.
  • execution timed out ou terminated: script ultrapassou request_terminate_timeout.

Para ver qual script está lento, ative o slowlog no pool e recarregue o PHP-FPM:

request_slowlog_timeout = 10s
slowlog = /var/log/php-fpm-exemplo-slow.log

O arquivo mostra o rastro de chamadas de cada requisição que passou de 10 segundos, apontando o plugin ou a função culpada.

4. Recursos do sistema

free -h                       # memória e swap
df -h                         # disco cheio derruba banco, sessões e logs
uptime                        # carga em relação ao número de núcleos
dmesg -T | grep -i "killed process"   # processos encerrados por falta de memória (OOM)

Se o OOM killer encerrou o MariaDB ou o PHP-FPM, o problema é dimensionamento: memory_limit × pm.max_children mais o innodb_buffer_pool_size passou da RAM da VM. Em Proxmox, confira também se a VM tem memória suficiente alocada e se o balão (ballooning) não está retirando memória dela. Veja também os artigos «OOM killer no Linux: como entender o uso de memória, configurar a swap e evitar que processos sejam encerrados» e «Disco cheio no Linux: como descobrir o que ocupa espaço e liberar com segurança».

5. Banco de dados

mariadb -e "SHOW FULL PROCESSLIST;"

Muitas consultas no estado Locked, Sending data ou rodando há minutos explicam um 504. Veja o artigo de tuning de MySQL/MariaDB desta base para habilitar o log de consultas lentas e veja também o artigo «MySQL lento: como achar as consultas culpadas com slow query log e EXPLAIN».

6. Tráfego anormal

Um pico de acessos de robôs ou um ataque à página de login ocupa todos os processos PHP:

awk '{print $1}' /var/log/nginx/access.log | sort | uniq -c | sort -rn | head
awk '{print $7}' /var/log/nginx/access.log | sort | uniq -c | sort -rn | head

Se poucos IPs ou uma única URL dominam a lista, bloqueie no firewall, aplique limit_req ou ative regras na Cloudflare. Veja também os artigos «Como instalar um WAF no servidor: ModSecurity com OWASP CRS e Cloudflare» e «Proteção contra DDoS no servidor dedicado: o que a rede filtra e o que você deve configurar».

Correções rápidas mais comuns

  • Serviço parado: systemctl restart php8.4-fpm (e investigue a causa no journal).
  • Timeout legítimo (relatório, importação): aumente de forma coordenada o max_execution_time do PHP, o request_terminate_timeout do pool e o fastcgi_read_timeout ou proxy_read_timeout do Nginx. O menor dos três é o que vale. Atrás da Cloudflare, o limite de 100 s continua; rotinas longas devem ir para fila, cron ou CLI.
  • Falta de processos: ajuste pm.max_children conforme a memória disponível.
  • Disco cheio: limpe logs antigos (journalctl --vacuum-size=500M) e backups esquecidos no próprio servidor.

Como saber se funcionou

  • curl -s -o /dev/null -w "%{http_code} %{time_total}\n" https://exemplo.com.br retorna 200 em tempo aceitável.
  • O error.log do Nginx para de registrar novas linhas de upstream.
  • O log do PHP-FPM não mostra mais avisos de max_children.

Problemas comuns

  • O erro some ao reiniciar e volta horas depois: sinal de vazamento de memória ou de pico recorrente (cron, backup, robô). Cruze o horário com o crontab e o access log.
  • Só uma página dá 504: use o slowlog para achar a função lenta; geralmente é uma consulta sem índice ou uma API externa fora do ar.
  • 502 apenas em uploads grandes: confira client_max_body_size, upload_max_filesize e se o diretório temporário tem espaço.

Perguntas frequentes

O que significa o erro 502 Bad Gateway?

Que o servidor web ou o proxy (Nginx, Apache, Cloudflare) recebeu uma resposta inválida, ou nenhuma, da aplicação que está atrás dele. A causa mais comum é o PHP-FPM ou a aplicação parada.

Qual a diferença entre o erro 502 e o 504?

No 502, a conexão com a aplicação falhou ou a resposta veio inválida. No 504, a aplicação até recebeu a requisição, mas não respondeu dentro do tempo limite do proxy.

Reiniciar o PHP-FPM resolve o erro 502?

Resolve na hora quando o serviço parou, mas o erro volta se a causa continuar. Antes de reiniciar, veja o motivo no log do Nginx, no log do PHP-FPM e no journalctl.

O erro 502 pode ser problema na rede do datacenter?

Raramente. Se o servidor responde a ping e SSH e o log do Nginx mostra erros de upstream, o problema está na aplicação ou nos recursos da VM, não na rede.

O que é o erro 524 da Cloudflare?

É o equivalente da Cloudflare ao 504: seu servidor levou mais de 100 segundos para responder. Rotinas longas devem ir para fila, cron ou CLI.

Leitura complementar

Precisa de ajuda?

Se ficar com alguma dúvida, abra um ticket na área do cliente ou fale com o suporte pelo WhatsApp.

Esta resposta lhe foi útil? 0 Usuários acharam útil (0 Votos)

Leia também