Erro 502 Bad Gateway | Causas e Soluções

Um erro 502 Bad Gateway ocorre quando um servidor atuando como gateway ou proxy recebe uma resposta inválida de um servidor upstream. Isso tipicamente acontece em arquiteturas distribuídas onde um load balancer, CDN ou API gateway fica entre clientes e servidores de aplicação. Entre todos os códigos de status HTTP, o 502 é um dos mais impactantes porque aponta para uma falha entre camadas—não no cliente ou na origem final isoladamente.

O Que Significa 502 Bad Gateway

A Definição HTTP

Per a RFC 9110, 502 indica “o servidor, enquanto atuava como gateway ou proxy, recebeu uma resposta inválida de um servidor upstream que acessou enquanto tentava completar a requisição.”

Características principais:

• O servidor que você alcançou é um proxy, não a origem
• O proxy tentou alcançar o upstream mas obteve uma resposta ruim
• “Resposta inválida” inclui HTTP malformado, resposta vazia ou connection reset

502 vs 503 vs 504

Causas Comuns de 502 Bad Gateway

1. Servidor de Aplicação Não Está Rodando

O servidor upstream não está aceitando conexões:

# Verifique se aplicação está rodando
systemctl status sua-app
netstat -tlnp | grep :3000

2. Servidor de Aplicação Crasou

O processo crashou enquanto tratava a requisição:

# Verifique logs da aplicação
journalctl -u sua-app -f
# Ou logs específicos da aplicação
tail -f /var/log/app/error.log

3. Incompatibilidade de Protocolo

O proxy espera HTTP mas o upstream envia algo diferente:

• Incompatibilidade HTTP/1.1 vs HTTP/2
• Incompatibilidade de configuração SSL/TLS
• Falhas de upgrade WebSocket

4. Resposta Muito Grande

A resposta upstream excede limites de buffer:

Nginx:

# Correção: Aumente tamanhos de buffer
proxy_buffer_size 128k;
proxy_buffers 4 256k;
proxy_busy_buffers_size 256k;

5. Connection Reset

O upstream fechou a conexão inesperadamente:

• Timeout da aplicação antes do timeout do proxy
• Esgotamento de memória causando kill do processo
• Problemas de rede entre proxy e upstream

6. Porta ou Endereço Errado

O proxy conecta ao upstream errado:

# Verifique configuração upstream
upstream backend {
    server 127.0.0.1:3000;  # Endereço correto?
}

Troubleshooting de Erros 502

Passo 1: Identifique Qual Camada Gerou o 502

Cliente → [CDN](/pt-br/learning/cdn/o-que-e-uma-cdn/) → [Load Balancer](/pt-br/learning/performance/o-que-e-balanceamento-de-carga/) → API Gateway → Aplicação
          ↑         ↑               ↑              ↑
        502       502             502           (origem do problema)

Verifique headers de resposta:

• Server: Identifica qual servidor respondeu
• X-Cache-Status: Informação do CDN
• Via: Informação da cadeia de proxies

Passo 2: Verifique Saúde do Servidor Upstream

# Teste conexão direta ao upstream
curl http://localhost:3000/health

# Verifique se porta está escutando
netstat -tlnp | grep :3000

# Verifique status do processo
ps aux | grep node
systemctl status sua-app

Passo 3: Verifique Logs do Proxy/Gateway

Nginx:

tail -f /var/log/nginx/error.log
# Procure por: "upstream sent an invalid response"
# Procure por: "connect() failed"
# Procure por: "Connection refused"

HAProxy:

tail -f /var/log/haproxy.log
# Procure por: "sH" (status 502)

Azion:

Real-Time Events → filtrar por status 502
# Verifique os campos upstream_cache_status e upstream_response_time

Cloud Load Balancer: Verifique dashboards de logs e métricas do provedor cloud.

Passo 4: Verifique Conectividade de Rede

# Teste do servidor proxy para upstream
curl -v http://upstream-server:port/

# Verifique regras de firewall
iptables -L -n

# Verifique resolução DNS
nslookup upstream-server

Passo 5: Compare Configurações de Timeout

O timeout do proxy deve ser maior que o timeout da aplicação upstream:

# Timeouts de proxy Nginx
proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;

Como Corrigir Erros 502

Corrija Problemas do Servidor de Aplicação

# Reinicie a aplicação
systemctl restart sua-app

# Verifique crashes
journalctl -u sua-app -n 100

# Monitore recursos
top -p $(pgrep -f "node.*app")

Corrija Configuração do Nginx

upstream backend {
    server 127.0.0.1:3000 max_fails=3 fail_timeout=30s;
    keepalive 32;
}

server {
    location / {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";

        # Aumente timeouts
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;

        # Aumente buffers para respostas grandes
        proxy_buffer_size 128k;
        proxy_buffers 4 256k;
    }
}

Corrija Health Checks

Garanta que o proxy tenha health checks precisos:

# Health checks passivos do Nginx
upstream backend {
    server 127.0.0.1:3000 max_fails=3 fail_timeout=30s;
}

# Health checks ativos do HAProxy
backend app_servers
    balance roundrobin
    option httpchk GET /health
    server app1 127.0.0.1:3000 check inter 5s fall 3 rise 2

# Azion: configure health checks via Origins no Console
# Defina path, intervalo e limiar de falha por origem

Implemente Circuit Breakers

Previna falhas em cascata:

const circuitBreaker = new CircuitBreaker(fetchFromUpstream, {
  timeout: 5000,
  errorThresholdPercentage: 50,
  resetTimeout: 30000
});

circuitBreaker.fire()
  .catch(err => {
    // Retorne fallback ou 503
  });

Perguntas Frequentes

Qual a diferença entre 502 e 504? 502 significa que o upstream enviou uma resposta inválida. 504 significa que o upstream não respondeu (timeout).

Por que 502 acontece após deploy? Causas comuns: aplicação não inicia, porta errada, variáveis de ambiente ausentes, problemas de migração de banco.

Como corrijo 502 no Kubernetes? Verifique status do pod, logs, readiness probes e seletores de serviço.

CDNs podem causar erros 502? Sim. Se a origem retorna uma resposta inválida, o CDN retornará 502 ao cliente.

Clientes devem tentar novamente em 502? Apenas para métodos idempotentes (GET, PUT, DELETE). Use backoff exponencial.

O que significa Nginx “upstream prematurely closed connection”? A aplicação fechou a conexão antes de enviar uma resposta completa. Verifique logs da aplicação para crashes ou timeouts.