1. Significado
O 504 é devolvido por um proxy, balanceador ou CDN que encaminhou a requisição para um servidor (o upstream) e não recebeu resposta dentro do tempo limite. A aplicação pode estar lenta, travada ou esperando algo (banco, API externa).
2. Diferença para 502 e 503
| Código | Situação típica |
|---|---|
| 502 Bad Gateway | upstream respondeu algo inválido ou a conexão foi recusada/derrubada (veja 502) |
| 503 Service Unavailable | serviço indisponível ou sobrecarregado, muitas vezes de propósito (manutenção, limite) |
| 504 Gateway Timeout | upstream existe, mas não respondeu a tempo |
3. Como investigar
- Meça direto na aplicação, sem o proxy:
curl -w "%{time_total}\n" -o /dev/null -s http://127.0.0.1:3000/rota. Se demora, o problema é a app. - Veja o log do proxy: no Nginx,
upstream timed out (110: Connection timed out)noerror.logconfirma o 504. - Procure a causa na aplicação: consulta SQL lenta (EXPLAIN e índices), chamada a API externa sem timeout, fila cheia, poucos workers.
- Confira CPU, memória e conexões do banco no momento do erro (top).
4. Ajustando os timeouts do Nginx
location /api/ {
proxy_pass http://app;
proxy_connect_timeout 5s;
proxy_send_timeout 60s;
proxy_read_timeout 60s; # padrão: 60s
}
Aumentar o proxy_read_timeout só mascara a lentidão. Faça isso para rotas que realmente demoram (exportações, relatórios) e, de preferência, mova trabalho pesado para uma fila em segundo plano com resposta imediata.
5. Em CDN e nuvem
Balanceadores e CDNs têm limites próprios de tempo (muitos entre 30 e 100 segundos) que não mudam só no Nginx. Consulte a documentação do serviço.
Continue explorando
← erros · 502 Bad Gateway · 500 · Nginx proxy reverso · Load balancer
Veja também o hub de conteúdo, o glossário e os cursos gratuitos.