~ / hub / erros / Erro 504 Gateway Timeout
4 out 2026errosguia de solução

Erro 504 Gateway Timeout

O proxy esperou a aplicação responder e desistiu. Descubra por que ela demora.

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ódigoSituação típica
502 Bad Gatewayupstream respondeu algo inválido ou a conexão foi recusada/derrubada (veja 502)
503 Service Unavailableserviço indisponível ou sobrecarregado, muitas vezes de propósito (manutenção, limite)
504 Gateway Timeoutupstream existe, mas não respondeu a tempo

3. Como investigar

  1. 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.
  2. Veja o log do proxy: no Nginx, upstream timed out (110: Connection timed out) no error.log confirma o 504.
  3. Procure a causa na aplicação: consulta SQL lenta (EXPLAIN e índices), chamada a API externa sem timeout, fila cheia, poucos workers.
  4. 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.

DICA Defina timeout em toda chamada externa da aplicação (banco, HTTP). Sem isso, uma dependência lenta vira 504 para o usuário.

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.

Quer aplicar no seu time?

Diagnóstico gratuito de 30 minutos.

solicitar →