HTTPTools

HTTP 504 Gateway Timeout

O intermediário desistiu de esperar: o servidor upstream não respondeu dentro do limite de tempo do proxy.

O que significa o HTTP 504

HTTP 504 Gateway Timeout é emitido por um proxy, load balancer ou CDN cuja requisição ao servidor upstream não recebeu resposta dentro do seu tempo limite. Diferente do 502 — onde o upstream respondeu mal — com o 504 ele simplesmente não respondeu a tempo.

A causa raiz é quase sempre algo lento nos bastidores: uma consulta de banco de dados cara, uma API externa que não responde, ou um pool de threads da aplicação esgotado pela carga.

Causas comuns de erros 504

  • Uma consulta de banco de dados lenta ou índice ausente fazendo um endpoint demorar mais do que o proxy permite.
  • A aplicação esperando por uma API externa que ela mesma está lenta ou fora do ar.
  • Backend saturado: todos os workers ocupados, requisições enfileirando além do timeout.
  • Problemas de rede entre proxy e upstream (roteamento, perda de pacotes, DNS).
  • Incompatibilidade de timeout: a aplicação legitimamente precisa de 60s, o proxy corta em 30s.

Como corrigir como visitante

  • Tente novamente após um momento — um único 504 é frequentemente uma requisição lenta isolada, não uma interrupção.
  • Para uma ação que você enviou (pagamento, pedido), verifique se ela realmente foi concluída antes de tentar novamente.

Como corrigir como desenvolvedor

  • Encontre o endpoint lento nos logs de acesso/APM: corrija a consulta, adicione índices, armazene o resultado em cache.
  • Mova trabalho lento para jobs em segundo plano e retorne rapidamente com um status que o cliente possa consultar.
  • Alinhe os orçamentos de timeout de ponta a ponta (app < proxy < CDN) para que o elo mais lento seja conhecido e intencional.
  • Adicione circuit breakers em torno de APIs externas instáveis em vez de deixá-las travar seus workers.

Exemplo de resposta

HTTP/1.1 504 Gateway Timeout
Server: nginx
Content-Type: text/html

<html><body><h1>504 Gateway Timeout</h1></body></html>

Perguntas frequentes

Qual é a diferença entre 504 e 502?

504 significa que o upstream nunca respondeu dentro do tempo limite; 502 significa que ele respondeu com algo inválido.

Um 504 é um problema de conexão do usuário?

Não — é entre o proxy do site e seu backend. A rede do usuário está bem.

Minha requisição enviada foi processada se recebi um 504?

Possivelmente sim — o timeout atingiu a resposta, não necessariamente o processamento. Verifique o estado antes de tentar novamente cegamente ações não idempotentes.