502 Bad Gateway: o que significa de verdade e como resolver

Você abre o seu site e, em vez do conteúdo, vê uma página em branco com a mensagem 502 Bad Gateway. Parece grave, mas na maioria dos casos a solução é simples. Vamos entender o que está acontecendo e como colocar o seu site de volta no ar.

O que o 502 realmente significa?

Quando um visitante acessa uma página, a requisição passa por duas camadas: um servidor web frontend (geralmente o Nginx) e um servidor de aplicação backend (PHP-FPM, Apache, Node.js ou outro). O Nginx recebe a requisição, encaminha para o backend e aguarda uma resposta.

502 Bad Gateway significa que o Nginx tentou obter uma resposta do backend, mas recebeu algo inválido ou não recebeu resposta alguma. O backend travou, recusou a conexão ou retornou algo que o Nginx não conseguiu interpretar.

info

Um engano muito comum: 502 não significa que o seu servidor está fora do ar. O servidor em si está funcionando bem — o problema está na aplicação por trás do Nginx.

Causas mais comuns

O serviço backend parou. Este é o motivo número um. O PHP-FPM travou, o Apache travou ou um processo do Node.js morreu silenciosamente. O Nginx simplesmente não tem com quem se comunicar.

O servidor está sem memória RAM. Quando a memória acaba, o Linux pode encerrar automaticamente os processos que consomem mais recursos. Esse mecanismo se chama OOM killer, e o PHP-FPM ou o MySQL costumam ser as primeiras vítimas. Se isso acontece com frequência, considere adicionar um arquivo de swap como medida de segurança.

O pool de workers do PHP-FPM está esgotado. Se o seu site recebe mais requisições simultâneas do que o PHP-FPM consegue atender, as novas requisições ficam na fila e acabam expirando. Isso costuma acontecer quando bots de mecanismos de busca rastreiam o seu site de forma muito agressiva — escrevemos sobre como lidar com isso no nosso guia de bloqueio de bots.

Socket ou porta mal configurados. O Nginx espera encontrar o PHP-FPM em um socket Unix ou porta TCP específica. Se o caminho na configuração do Nginx não corresponder à configuração do PHP-FPM, você verá erros 502 imediatamente após qualquer alteração.

Como diagnosticar

Para executar os passos abaixo, conecte-se ao seu servidor via SSH. Você pode aprender como fazer isso no nosso artigo sobre SSH.

Passo 1. Verifique se o backend está rodando

Verifique o status do seu serviço backend:

sudo systemctl status php8.2-fpm

Substitua php8.2-fpm pela sua versão real do PHP ou pelo nome do seu serviço backend. Se a saída mostrar inactive (dead) ou failed, aí está o problema. Reinicie o serviço:

sudo systemctl restart php8.2-fpm

Em seguida, verifique o status novamente para confirmar que ele iniciou com sucesso.

Passo 2. Verifique o log de erros do Nginx

O log de erros quase sempre diz exatamente o que aconteceu:

sudo tail -30 /var/log/nginx/error.log

Se você usa o FASTPANEL®, também pode ver os logs diretamente na interface web: abra o card do site, vá para a seção «Logs» e consulte a aba «Frontend Error Log».

Estas são as mensagens de erro mais comuns e o que elas significam:

connect() failed - Connection refused — o serviço backend não está rodando. Reinicie-o conforme mostrado no Passo 1.

connect() failed - No such file or directory — o Nginx está tentando acessar um socket Unix que não existe. Verifique se o caminho do socket na sua configuração do Nginx corresponde ao que o PHP-FPM realmente cria.

upstream sent too big header — o backend retornou headers HTTP grandes demais para o buffer padrão. Adicione estas linhas na configuração do seu site no Nginx, dentro do bloco server:

fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;

Após editar, teste a configuração e recarregue o Nginx:

sudo nginx -t && sudo systemctl reload nginx

Passo 3. Verifique os recursos do servidor

free -h

Se a coluna available mostrar menos de 100–200 MB de memória livre, o servidor provavelmente está sem RAM. Verifique o que está consumindo:

ps aux --sort=-%mem | head -10

atenção

Se a falta de memória é a causa raiz, a solução temporária mais rápida é adicionar um arquivo de swap. Porém, o swap em disco é muito mais lento do que a RAM e não deve ser tratado como solução permanente. Se o seu servidor fica sem memória com regularidade, é hora de otimizar as aplicações ou migrar para um plano com mais RAM.

Conclusão

Um 502 Bad Gateway é quase sempre um problema de backend — um serviço travado, workers esgotados ou memória insuficiente. Verifique o status do backend, leia o log de erros do Nginx e analise o uso de recursos. Na grande maioria dos casos, você encontrará a resposta em poucos minutos.

Se preferir não lidar com isso sozinho, na kodu.cloud oferecemos suporte técnico gratuito 24/7 com cada VPS e servidor dedicado. Todos os nossos clientes também recebem o FASTPANEL® Extended sem custo adicional, o que torna a análise de logs e o gerenciamento de serviços muito mais fáceis através de uma interface web.