Erro 504 Gateway Timeout: como diagnosticar e resolver

O erro 504 Gateway Timeout ocorre quando um gateway ou proxy não recebe a resposta do servidor de origem dentro do prazo. Ele difere do 502: no 504, o intermediário esperou, mas não recebeu uma resposta HTTP a tempo. A investigação deve seguir a requisição de fora para dentro.

Resposta direta: como corrigir 504

Registre horário, rota e request ID; confirme qual proxy respondeu; teste a origem diretamente; compare os timeouts; examine duração da aplicação, consultas ao banco e chamadas externas. Corrija o trabalho lento ou transforme-o em tarefa assíncrona. Aumentar timeout é uma medida temporária quando a duração longa é legítima e controlada.

Passo 1: desenhe o caminho da requisição

navegador -> CDN/WAF -> balanceador -> Nginx -> aplicação -> banco/API externa

Cada seta pode ter seu próprio limite. Um CDN pode desistir antes do Nginx; o Nginx pode desistir antes da aplicação; a aplicação pode aguardar uma consulta sem timeout. Descubra quem gerou a página de erro pelos cabeçalhos e pelo painel do fornecedor.

Passo 2: reproduza com identificação

curl -v --max-time 70 \
  -H "X-Request-ID: diagnostico-504-001" \
  https://exemplo.com/relatorio

Teste a mesma rota diretamente na origem apenas em ambiente autorizado. Se a origem também demora, o problema está nela ou abaixo dela. Se a origem é rápida, examine proxy, DNS, conexão e capacidade intermediária.

Passo 3: correlacione logs

Procure o request ID em todas as camadas. Registre início, fim e duração de cada dependência. Métricas úteis incluem p50, p95 e p99, conexões ativas, saturação de CPU, memória, fila, pool do banco e consultas lentas.

Passo 4: trate banco e dependências

Use EXPLAIN (ANALYZE, BUFFERS) em uma cópia segura ou consulta controlada. Não execute análise destrutiva em produção. Verifique filtros, índices, volume retornado e N+1. Para serviços externos, defina timeouts menores que o prazo total e retries apenas em operações idempotentes, com espera crescente e aleatoriedade.

Passo 5: tire trabalhos longos da requisição

Exportação, importação, processamento de imagem e relatório extenso não precisam manter uma conexão HTTP aberta. A API pode criar um job, responder 202 Accepted, processar em fila e disponibilizar o resultado depois. Garanta idempotência para evitar duplicação quando o cliente repetir.

Configuração Nginx com cautela

location /api/ {
  proxy_connect_timeout 5s;
  proxy_send_timeout 30s;
  proxy_read_timeout 30s;
  proxy_pass http://aplicacao;
}

Os valores são exemplos, não recomendação universal. proxy_read_timeout mede o intervalo entre leituras, não o tempo total da operação. Antes de aumentá-lo, estime impacto de conexões presas e capacidade.

Como prevenir novos 504

• SLO por jornada crítica;
• timeout explícito em toda chamada externa;
• painel de latência por rota e dependência;
• alerta antes da saturação;
• teste de carga com cenário realista;
• filas com limite, retentativa e dead-letter;
• endpoint de saúde que não dependa de tudo;
• runbook com responsáveis e rollback.

Leia também erro 502 no Nginx, erro 500 em API e o guia de monitoramento de APIs.

Perguntas frequentes

Reiniciar o servidor resolve?

Pode liberar um recurso temporariamente, mas não explica a causa. Preserve métricas e logs antes de reiniciar quando a operação permitir.

Aumentar o timeout é seguro?

Só quando a duração é esperada e a capacidade foi calculada. Caso contrário, o sistema acumula trabalho e falha mais tarde.

Fontes primárias

• MDN: status 504 Gateway Timeout
• Nginx: proxy_read_timeout
• RFC 9110: status 504