1. O que o 502 significa
O reverse proxy (Nginx, Caddy, load balancer, Cloudflare) não obteve uma resposta válida do backend (upstream).
2. Onde olhar primeiro
sudo tail -n 100 /var/log/nginx/error.log
curl -v http://127.0.0.1:3000/health
ss -lntp | grep -E '3000|8080'
systemctl status minha-api
3. Causas comuns
- Processo do app caiu ou ainda não subiu
proxy_passapontando para host/porta erradosproxy_read_timeoutbaixo demais para a operação- Upstream só escuta em IPv6 ou só em socket Unix mal configurado
- OOM killer matou o processo (veja
dmesg)
4. Timeouts no Nginx
location / {
proxy_pass http://127.0.0.1:3000;
proxy_connect_timeout 5s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
5. Protocolo de incidente rápido
- Confirmar se o upstream responde localmente
- Reiniciar o app com cuidado (sem perder a sessão de debug)
- Se acabou de deployar: rollback da versão anterior
- Registrar horário, versão e trecho do error.log