502 Bad Gateway: o que realmente significa e como corrigi-lo

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

O que 502 realmente significa?

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

Um 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 equívoco comum: 502 não significa que o seu servidor está fora do ar. O próprio servidor está bem - é a aplicação por trás do Nginx que está com dificuldades.

Causas mais comuns

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

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

O pool de workers do PHP-FPM está esgotado. Se o seu site receber mais solicitações simultâneas do que o PHP-FPM consegue processar, novas solicitações entram em fila e acabam expirando. Isso costuma acontecer quando bots de mecanismos de busca rastreiam seu site de forma agressiva demais - escrevemos sobre como lidar com isso em nosso guia de bloqueio de bots.

Socket ou porta configurado incorretamente. O Nginx espera encontrar o PHP-FPM em um socket Unix específico ou em uma porta TCP. 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 as etapas a seguir, conecte-se ao seu servidor via SSH. Você pode aprender como fazer isso em nosso artigo sobre SSH.

Etapa 1. Verifique se o backend está em execução

Verifique o status do seu serviço de backend:

sudo systemctl status php8.2-fpm

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

sudo systemctl restart php8.2-fpm

Depois verifique o status novamente para garantir que ele foi iniciado com sucesso.

Etapa 2. Verifique 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 FASTPANEL®, também poderá 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 de backend não está em execução. Reinicie-o conforme mostrado na Etapa 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 grandes demais 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

Etapa 3. Verifique os 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 isso:

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

atenção

Se a pressão de memória for a causa raiz, a correção temporária mais rápida é adicionar um arquivo swap. No entanto, o swap em disco é muito mais lento do 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 migrar para um plano com mais RAM.

Conclusão

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

Se você preferir não lidar com isso sozinho, na kodu.cloud fornecemos 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 significativamente mais fáceis por meio de uma interface web.