Um proxy não recebeu resposta a tempo.
Quando usar
O app upstream está lento demais ou travado.
Causas comuns e soluções
O proxy desistiu de esperar pelo upstream. Causas típicas: uma consulta lenta ao banco de dados ou chamada lenta a uma API externa, um worker em deadlock, poucos workers para o tráfego, ou um firewall descartando pacotes silenciosamente. Os timeouts são em camadas, e o mais curto vence: o proxy_read_timeout do nginx é de 60 segundos por padrão, o AWS ALB encerra por inatividade depois de 60, o API Gateway depois de 29, e a Cloudflare mostra o seu próprio 524 depois de 100 segundos.
Descubra onde o tempo está indo: confira nos logs da aplicação a duração das requisições, procure consultas lentas e cronometre a mesma requisição direto na origem, sem passar pelo proxy. Aumentar timeouts só esconde o problema; mova tarefas longas para um worker em segundo plano e retorne 202 com uma URL de status. O trabalho ainda pode terminar depois do 504, então repetir requisições não idempotentes pode duplicá-lo.
Erro do servidor (5xx)
Os códigos 5xx são erros do servidor: a requisição pode estar certa, mas o servidor ou algo por trás dele falhou. Vale a pena configurar alertas para eles.
Como fica
HTTP/1.1 504 Gateway TimeoutComo enviar
| Node.js / Express | res.status(504).end() |
|---|---|
| Python / Flask | return '', 504 |
| nginx | return 504; |
Como verificar
curl -s -o /dev/null -w "%{http_code}\n" https://example.com/