502 Gateway Inválido: o que realmente significa e como corrigir

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

O que um 502 realmente significa?

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

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

info

Um equívoco comum: 502 não significa que seu servidor está inativo. O próprio servidor está bem - é a aplicação por trás do Nginx que está com problemas.

Causas mais comuns

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

O servidor está ficando sem RAM. Quando a memória fica baixa, o Linux pode encerrar processos que consomem muitos recursos automaticamente. Esse mecanismo é chamado de OOM killer, e o PHP-FPM ou MySQL costumam ser suas primeiras vítimas. Se isso acontecer regularmente, considere adicionar um arquivo de swap como uma rede de segurança.

Pool de workers do PHP-FPM esgotado. Se o seu site receber mais solicitações simultâneas do que o PHP-FPM pode lidar, novas solicitações entram na fila e eventualmente expiram. Isso geralmente acontece quando bots de mecanismos de busca rastreiam seu site agressivamente demais - escrevemos sobre como lidar com isso em 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íficos. 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 realizar os seguintes passos, conecte-se ao seu servidor via SSH. Você pode aprender como fazer isso em nosso artigo sobre SSH.

Passo 1. Verificar se o backend está em execução

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 nome do serviço backend. Se a saída mostrar inactive (dead) ou failed, esse é o seu problema. Reinicie-o:

sudo systemctl restart php8.2-fpm

Em seguida, verifique o status novamente para ter certeza de que ele iniciou com sucesso.

Passo 2. Verificar o log de erros do Nginx

O log de erros quase sempre informa exatamente o que deu errado:

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

Se você estiver usando o FASTPANEL®, também pode visualizar os logs diretamente na interface web: abra o cartão do site, vá para a seção "Logs" e verifique a aba "Frontend Error Log".

Aqui estão as mensagens de erro mais comuns e o que elas significam:

connect() failed - Connection refused - o serviço backend não está em execução. Reinicie-o como 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 cabeçalhos HTTP muito grandes para o buffer padrão. Adicione estas linhas à 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. Verificar recursos do servidor

free -h

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

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

atenção

Se a pressão de memória for a causa raiz, a solução temporária mais rápida é adicionar um arquivo de swap. No entanto, o swap em disco é muito mais lento que a RAM e não deve ser tratado como uma solução permanente. Se o seu servidor regularmente fica sem memória, é hora de otimizar suas aplicações ou fazer um upgrade para um plano com mais RAM.

Conclusão

Um 502 Gateway Inválido é 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 vasta maioria dos casos, você encontrará a resposta em minutos.

Se você prefere não lidar com isso sozinho, na kodu.cloud oferecemos suporte técnico gratuito 24 horas por dia, 7 dias por semana, 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 significativamente mais fáceis através de uma interface web.