Erro 502 Nginx: causas e como resolver

O erro 502 Bad Gateway no Nginx indica que o servidor não conseguiu obter uma resposta válida de um servidor upstream. Isso pode causar interrupções sérias em aplicações web, afetando a experiência do usuário e a confiabilidade do serviço.

Esse erro geralmente ocorre em ambientes onde o Nginx atua como um proxy reverso, redirecionando requisições para servidores de aplicação como Node.js, PHP-FPM, entre outros. O impacto técnico é significativo, pois usuários podem ser impedidos de acessar funcionalidades críticas da aplicação.

Causas Prováveis

• Servidor upstream inativo ou mal configurado
• Problemas de rede entre o Nginx e o servidor upstream
• Timeouts de conexão
• Erros de configuração no Nginx

Diagnóstico

Para diagnosticar o erro 502, siga os passos abaixo:

1. Verifique os logs do Nginx em /var/log/nginx/error.log para mensagens de erro.
2. Cheque se o servidor upstream está em execução e acessível.
3. Teste a conectividade entre o Nginx e o servidor upstream usando curl.

Correção Passo a Passo

Abaixo estão as etapas para corrigir o erro 502:

1. Verifique a configuração do servidor upstream no arquivo de configuração do Nginx:

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

2. Certifique-se de que o servidor upstream está em execução:

systemctl status nome-do-serviço

3. Verifique os timeouts no Nginx:

proxy_read_timeout 90;
proxy_connect_timeout 90;

4. Reinicie o Nginx após fazer alterações:

sudo systemctl restart nginx

Riscos em Produção

Resolver o erro 502 é crítico para a continuidade do serviço. Ignorar esse erro pode levar a uma experiência negativa do usuário e perda de receita. Além disso, uma configuração inadequada pode resultar em vulnerabilidades de segurança.

Prevenção

Para prevenir futuros erros 502, considere as seguintes práticas:

• Monitore a saúde do servidor upstream regularmente.
• Implemente um sistema de balanceamento de carga.
• Configure alertas para erros no Nginx.

FAQ

O que é um erro 502 Bad Gateway?

É um erro que indica que o servidor Nginx não conseguiu obter uma resposta válida de um servidor upstream.

Como posso saber se o problema é no Nginx ou no servidor upstream?

Verifique os logs do Nginx e teste a conectividade com o servidor upstream usando curl.

É seguro reiniciar o Nginx para corrigir o erro 502?

Sim, reiniciar o Nginx pode ajudar a aplicar novas configurações e resolver problemas temporários.

Causa	Sintoma	Como Confirmar	Correção
Servidor upstream inativo	Erro 502	Logs do Nginx	Iniciar o servidor upstream
Timeouts de conexão	Erro 502	Logs do Nginx	Aumentar timeouts no Nginx
Problemas de rede	Erro 502	Teste de conectividade	Resolver problemas de rede

Referências e próximos passos

• RFC 9110 — HTTP Semantics
• MDN Web HTTP
• OWASP API Security Project

Para projetar diagnóstico, autenticação e recuperação desde o início, conheça nosso serviço de APIs e integrações.