Erro 504 Gateway Timeout: o que significa e como resolver

O que é o erro 504 Gateway Timeout?

O 504 Gateway Timeout é um código de status HTTP que significa que um servidor atuando como gateway ou proxy não recebeu uma resposta a tempo do servidor upstream. O proxy ficou esperando o upstream responder, mas demorou demais, então o proxy desistiu e retornou um erro 504 para o seu navegador.

A RFC 9110 define assim: “O código de status 504 (Gateway Timeout) indica que o servidor, ao atuar como gateway ou proxy, não recebeu a tempo uma resposta de um servidor upstream que precisava acessar para concluir a requisição” (RFC 9110 §15.6.5).

A palavra-chave aqui é gateway. Um erro 504 sempre envolve pelo menos dois servidores: aquele ao qual você se conectou (o proxy/gateway) e o que está por trás dele (o upstream/origem) que não conseguiu responder. Proxies comuns incluem Nginx como proxy reverso, Cloudflare, AWS Application Load Balancer (ALB) e CloudFront.

Como o erro 504 aparece

O texto depende da camada que desistiu:

• 504 Gateway Time-out com “nginx” embaixo: nginx (ele escreve com hífen)
• 504 Gateway Time-out · The server didn't respond in time.: a página padrão do HAProxy
• Gateway Timeout · The gateway did not receive a timely response from the upstream server or application.: Apache na frente do PHP-FPM (mod_proxy_fcgi). Já o Apache fazendo proxy de um backend HTTP mostra Proxy Error · Error reading from remote server (um 502).
• ERROR · The request could not be satisfied · 504 ERROR: Amazon CloudFront
• Error 524: A timeout occurred: a versão do Cloudflare; ele chegou ao seu servidor, mas a resposta não veio a tempo
• Esta página não está funcionando · example.com demorou muito para responder. · Erro HTTP 504: Chrome, quando o 504 não traz página própria

Seja qual for o texto, a causa é a mesma: um proxy esperou pelo servidor atrás dele e a resposta não veio a tempo. (O Chrome usa a mesma frase “demorou muito para responder” quando o navegador não conseguiu nem conectar, mas aí o título é “Não é possível acessar esse site” e o código é ERR_CONNECTION_TIMED_OUT, não Erro HTTP 504: veja ERR_CONNECTION_TIMED_OUT.)

Como o erro 504 Gateway Timeout acontece

Para entender o erro 504, você precisa entender a cadeia de timeout entre o seu navegador e o servidor de origem. Uma requisição web típica passa por várias camadas, e cada camada tem sua própria configuração de timeout.

Este é um fluxo típico de requisição: Navegador → CDN (Cloudflare) → Load Balancer → Nginx → PHP-FPM → Banco de dados. Se a consulta ao banco leva 90 segundos e o fastcgi_read_timeout do nginx é de 60 segundos, o nginx para de esperar e devolve um 504 ao load balancer, que o repassa pela CDN até o seu navegador.

O servidor que devolve o 504 costuma ser um proxy no meio do caminho, não a aplicação em si. A aplicação ainda pode estar trabalhando na requisição, ou pode estar travada.

Fontes: Cloudflare 524, configurações de origem do CloudFront, Google Cloud e a documentação de cada servidor. O max_execution_time do PHP (30 segundos) não gera 504: um script que o atinge para com um erro fatal, que aparece como 500. E no Linux ele não conta o tempo esperando o banco de dados ou outra E/S, então um script preso numa consulta lenta pode rodar bem mais que isso.

Causas comuns do erro 504 Gateway Timeout

Os motivos habituais para um proxy cansar de esperar:

• Uma requisição lenta: uma consulta pesada ao banco, um relatório ou uma chamada a uma API de terceiros lenta demora mais que o timeout do proxy.
• Servidor sobrecarregado: CPU em 100%, pouca memória ou todos os workers do PHP-FPM ocupados, então as novas requisições esperam na fila até o proxy desistir.
• Gargalos no banco de dados: consultas lentas, índices ausentes, tabelas bloqueadas ou um pool de conexões esgotado.
• Timeouts baixos demais: os 60 segundos do nginx são curtos para um backend que realmente precisa de mais tempo (uma exportação, uma importação, um upload grande).
• Problemas de rede entre o proxy e a origem: perda de pacotes ou um firewall que descarta em silêncio os pacotes do proxy (um firewall que os rejeita dá 502).
• O limite fixo de uma CDN: o Cloudflare espera 125 segundos no Free, Pro e Business, não importa o que o seu nginx permita, e então mostra o Error 524.
• Uma enxurrada de tráfego: um pico ou um ataque ocupa os workers, e as requisições normais não são respondidas a tempo. (Um servidor que sabe que está sobrecarregado pode responder com 503.)

Solução para visitantes: o que você pode fazer

Se você está vendo um erro 504 no site de outra pessoa, o problema está no servidor deles — não no seu dispositivo. No entanto, vale a pena tentar algumas coisas.

• Espere um minuto e recarregue: muitos 504 duram só o tempo de um momento de pico no servidor.
• Veja se caiu para todo mundo: o Website Down Checker abre a página de 11 lugares. Se eles também recebem 504, o problema é do site.
• Tente outra rede: dados móveis em vez de Wi-Fi, ou sem VPN, caso o seu próprio proxy ou VPN seja o gateway estourando o tempo.
• Confira a página de status ou as redes sociais do site: sites movimentados costumam avisar sobre quedas.

Correção 1: aumentar configurações de Timeout (Nginx e Apache)

A correção mais comum para erros 504 é aumentar os valores de timeout no seu proxy reverso. Se o seu backend legitimamente precisa de mais de 60 segundos (o padrão), o proxy precisa saber que deve esperar mais.

# nginx — reverse proxy to a backend (Node.js, Python, etc.)
location / {
    proxy_pass http://backend;
    proxy_read_timeout 300;
    proxy_send_timeout 300;
}

# nginx — FastCGI (PHP-FPM)
location ~ \.php$ {
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    fastcgi_read_timeout 300;
    fastcgi_send_timeout 300;
    include fastcgi_params;
}

# Leave proxy_connect_timeout / fastcgi_connect_timeout at their defaults:
# nginx caps them at about 75 seconds, and a dead backend should fail fast.

No Apache, adicione ProxyTimeout 300 no seu VirtualHost ou use ProxyPass / http://backend:8080/ timeout=300 para um único backend.

Importante: os timeouts de leitura e de envio medem o intervalo entre duas operações de leitura ou escrita seguidas, não o tempo total da transferência. Assim, proxy_read_timeout 300 quer dizer “se nenhum dado chegar por 300 segundos”, e não “a resposta inteira deve terminar em 300 segundos”. Recarregue depois de alterá-los: sudo nginx -t && sudo systemctl reload nginx.

Atrás de uma CDN, o limite dela continua valendo: o Cloudflare corta aos 125 segundos (do Free ao Business) e o CloudFront aos 30 por padrão, então aumentar o nginx além disso não muda nada para quem chega pela CDN.

Correção 2: otimizar scripts lentos e consultas ao banco de dados

Se o seu backend consistentemente excede o timeout, aumentar o valor do timeout apenas mascara o problema. A correção real é fazer o backend responder mais rápido.

• Encontre consultas lentas — Ative o log de consultas lentas do MySQL (slow_query_log = 1, long_query_time = 1) ou use EXPLAIN ANALYZE nas consultas suspeitas. Adicione índices faltando, evite SELECT * e pagine conjuntos de resultados grandes.
• Adicione cache — Use Redis ou Memcached para cachear resultados de consultas caras. Uma consulta que leva 5 segundos em cada carregamento de página deveria estar cacheada.
• Mova trabalho pesado para jobs em segundo plano — Geração de relatórios, envio de e-mails, processamento de imagens e importações de dados devem rodar em uma fila de jobs (Celery, Sidekiq, Bull), não no ciclo de requisição HTTP.
• Otimize chamadas de API — Se o seu backend chama APIs de terceiros lentas, adicione timeouts a essas chamadas e implemente circuit breakers para que uma API lenta não bloqueie todas as requisições.
• Reduza consultas N+1 — Consultas geradas por ORMs frequentemente fazem centenas de chamadas individuais ao banco de dados. Use eager loading ou consultas em batch para reduzir viagens de ida e volta.

Correção 3: verificar recursos do servidor (CPU, RAM, disco)

Se o servidor de origem está sobrecarregado, ele não consegue processar requisições rápido o suficiente, e o proxy dá timeout esperando. Verifique o que está consumindo recursos.

# Check CPU and memory usage
top -bn1 | head -20

# Check disk space (full disk = silent failures)
df -h

# Check memory details
free -m

# Find processes using the most CPU
ps aux --sort=-%cpu | head -10

# Find processes using the most memory
ps aux --sort=-%mem | head -10

# Check active network connections
ss -s

Se a CPU ou RAM está em 90%+, você precisa otimizar sua aplicação, encerrar processos descontrolados ou fazer upgrade do servidor. Se o espaço em disco está cheio, limpe arquivos de log antigos, backups ou arquivos temporários — um disco cheio pode travar silenciosamente bancos de dados e causar erros 504 em cascata.

Correção 4: verificar logs de erro

Os logs de erro dizem exatamente por que o proxy retornou 504. Sempre verifique os logs antes de tentar adivinhar a causa.

# Nginx error log (look for "upstream timed out")
tail -50 /var/log/nginx/error.log

# Apache error log
tail -50 /var/log/apache2/error.log       # Debian/Ubuntu
tail -50 /var/log/httpd/error_log          # CentOS/RHEL

# PHP-FPM log
tail -50 /var/log/php8.3-fpm.log

# System log (OOM kills, crashes)
tail -50 /var/log/syslog

Mensagens de log comuns por trás de um 504:

“upstream timed out (110: Connection timed out) while reading response header from upstream” (nginx): o backend demorou mais que o proxy_read_timeout (ou fastcgi_read_timeout). Acelere-o, ou aumente o timeout se a espera for legítima.

“upstream timed out (110: Connection timed out) while connecting to upstream” (nginx): o nginx nem conseguiu conectar a tempo: um firewall descartando pacotes, ou um backend ocupado demais para aceitar conexões.

“server reached pm.max_children setting” (PHP-FPM): todos os workers estão ocupados, então as requisições esperam na fila. Aumente o pm.max_children só se houver RAM para isso; senão, ache as requisições lentas que seguram os workers.

“Too many connections” (MySQL): o limite de conexões acabou. Novas conexões falham na hora (um 500, como o “Error establishing a database connection” do WordPress), enquanto as consultas que as seguram costumam ser as lentas por trás dos seus 504.

Correção 5: ajustar configurações do PHP-FPM

Em apps PHP (WordPress, Laravel, Magento), mantenha os timeouts em cadeia, cada camada um pouco maior que a de trás: fastcgi_read_timeout do nginx ≥ request_terminate_timeout do PHP-FPM ≥ max_execution_time do PHP.

Depois de mudar as configurações do PHP-FPM, reinicie-o (sudo systemctl restart php8.3-fpm, ajustando a versão). Se o fastcgi_read_timeout do nginx for menor que os limites do PHP, o nginx desiste primeiro e os visitantes veem um 504 enquanto o PHP ainda trabalha.

Correção 6: verificar configuração do CDN e proxy

Se o seu site está atrás de uma CDN como Cloudflare ou AWS CloudFront, a CDN tem seus próprios timeouts, que podem se sobrepor à configuração do seu servidor.

Cloudflare: no Free, Pro e Business, se a sua origem não começou a responder em 125 segundos, o Cloudflare desiste e mostra o Error 524 (Cloudflare). O conselho do próprio Cloudflare: acelere a requisição, mova os trabalhos longos para segundo plano ou sirva-os de um subdomínio só DNS (nuvem cinza); os planos Enterprise podem aumentar o limite.

CloudFront: aumente o response timeout da origem nas configurações de origem da distribuição (AWS). A AWS sugere corrigir primeiro a origem lenta. Em requisições GET e HEAD, o CloudFront tenta a origem de novo (3 tentativas de conexão por padrão), então a origem pode ver a mesma requisição várias vezes antes de o visitante receber o 504.

Para descobrir qual camada enviou o 504, veja os cabeçalhos da resposta no HTTP Header Checker: server: awselb/2.0 é um load balancer da AWS, x-cache: Error from cloudfront é o CloudFront e server: nginx é o nginx. Atrás do Cloudflare toda resposta diz server: cloudflare, então ali a pista é o próprio código (524 ou 504).

Correção 7: soluções específicas para WordPress

Sites WordPress são particularmente propensos a erros 504 devido a plugins pesados, inchaço no banco de dados e limites de hospedagem compartilhada. Aqui estão correções direcionadas.

• Identifique plugins lentos — Desative todos os plugins e reative um por um. Se você não consegue acessar o wp-admin, renomeie a pasta plugins via SSH: mv wp-content/plugins wp-content/plugins_disabled. Use o plugin Query Monitor para identificar consultas lentas ao banco de dados.
• Instale um plugin de cache — WP Super Cache, W3 Total Cache ou WP Rocket reduzem o processamento no servidor ao servir HTML estático em vez de executar PHP em cada requisição.
• Use cache de objetos — Instale Redis ou Memcached e um plugin de object cache para WordPress. Isso cacheia resultados de consultas ao banco de dados na memória, reduzindo a carga no MySQL.
• Limpe o banco de dados — Exclua revisões antigas de posts, transients, comentários de spam e metadados órfãos. Use WP-Optimize ou WP-Sweep. Adicione define('WP_POST_REVISIONS', 5); para limitar revisões futuras.
• Troque o wp-cron por um cron de verdade — as visitas à página disparam o WP-Cron, que executa as tarefas pendentes numa requisição loopback que ocupa um worker de PHP só dela. Adicione define('DISABLE_WP_CRON', true); ao wp-config.php e faça o servidor rodar wp cron event run --due-now a cada 5 minutos.

504 vs 502 vs 503 vs 408: qual a diferença?

Esses códigos de erro HTTP costumam ser confundidos. Veja o que cada um significa de fato.

A diferença essencial: um 502 significa que o proxy recebeu uma resposta quebrada, ou que a conexão foi recusada ou fechada; um 504 significa que o cronômetro do proxy acabou enquanto o upstream continuava em silêncio. Um 503 não precisa de proxy: qualquer servidor pode enviá-lo quando está sobrecarregado. Um 408 é um timeout do lado do cliente (classe 4xx), em que o servidor cansou de esperar o cliente.

Se você vê 502 e 504 juntos, o backend provavelmente está com dificuldade: requisições que estouram o tempo dão 504, e workers que travam ou são encerrados dão 502.

Se o que aparece é o 502 e não o 504, o nosso guia do 502 Bad Gateway percorre as mensagens do log de erros do nginx que o explicam, incluindo um caso real deste site.

O erro 504 afeta o SEO?

A documentação do Google descreve o que os erros 5xx causam (documentação do Google sobre rastreamento):

• O rastreamento fica mais lento no site todo, na proporção do número de URLs que retornam erros de servidor.
• As páginas indexadas são mantidas no início, mas URLs que retornam erro de servidor de forma persistente acabam removidas.
• O rastreamento se recupera aos poucos quando o servidor volta a responder com 2xx.

Como prevenir erros 504 Gateway Timeout

Prevenção é melhor do que apagar incêndios. Estas práticas vão manter seu servidor respondendo dentro dos limites de timeout.

• Configure monitoramento — um monitor de disponibilidade que carregue as páginas principais a cada poucos minutos pega os 504 antes de os usuários avisarem.
• Alinhe sua cadeia de timeout — Garanta que timeout do CDN ≥ timeout do proxy ≥ timeout da aplicação. Valores desalinhados causam erros 504 imprevisíveis.
• Implemente health checks — Balanceadores de carga e proxies devem verificar a saúde dos servidores upstream e redirecionar tráfego para longe de instâncias que não respondem.
• Use cache agressivamente — Cache de ativos estáticos, respostas de API e consultas ao banco de dados. Uma resposta cacheada nunca é lenta o suficiente para causar um 504.
• Auto-scale — Use escalonamento horizontal (mais instâncias) para que picos de tráfego não sobrecarreguem um único servidor.
• Mova trabalho pesado para segundo plano — Mova processamento de arquivos, geração de relatórios, envio de e-mails e importações em massa para filas de jobs em segundo plano. Nunca faça trabalho pesado dentro de uma requisição HTTP.
• Monitore consultas lentas — Ative o log de consultas lentas no MySQL/PostgreSQL. Configure alertas para consultas que excedam 1 segundo.
• Mantenha dependências saudáveis — Monitore APIs de terceiros das quais seu backend depende. Adicione timeouts e circuit breakers para que uma API lenta não cause erros 504 em cascata para todos os usuários.