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 definição oficial vem da RFC 9110 (HTTP Semantics), Seção 15.6.5, que afirma: "O código de status 504 (Gateway Timeout) indica que o servidor, ao atuar como gateway ou proxy, não recebeu uma resposta a tempo de um servidor upstream que precisava acessar para completar a requisição."

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

A mensagem de erro 504 varia dependendo do navegador, servidor web e CDN. Aqui estão as mensagens mais comuns que você vai encontrar.

• 504 Gateway Timeout

• 504 Gateway Time-out (padrão do Nginx — usa hífen)

• HTTP Error 504 — Gateway Timeout

• Esta página não está funcionando — [domínio] demorou muito para responder (Chrome / Edge)

• Gateway Timeout (Firefox)

• Error 504

• 504 Gateway Time-out — The server didn't respond in time (Apache com mod_proxy)

• Error 524: A timeout occurred (específico do Cloudflare — tecnicamente não é 504, mas a causa raiz é a mesma)

• ERROR — The request could not be satisfied — 504 ERROR (AWS CloudFront)

Independentemente do texto exibido, a causa subjacente é sempre a mesma: um servidor proxy ficou esperando o servidor upstream responder e o upstream não respondeu dentro da janela de timeout configurada.

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.

Aqui está um fluxo de requisição típico: Navegador → CDN (Cloudflare) → Balanceador de Carga → Nginx → PHP-FPM → Banco de Dados. Se a consulta ao banco de dados leva 90 segundos e o proxy_read_timeout do Nginx está configurado para 60 segundos, o Nginx para de esperar e retorna um 504 para o balanceador de carga, que passa de volta para o seu navegador.

O servidor que retorna o 504 é sempre o intermediário (proxy ou gateway), nunca o servidor de origem em si. O servidor de origem simplesmente não respondeu a tempo — ele pode ainda estar processando a requisição, ou pode ter travado completamente.

Causas Comuns do Erro 504 Gateway Timeout

Entender a causa raiz é o caminho mais rápido para resolver o problema. Aqui estão os motivos mais comuns pelos quais um servidor retorna 504, ordenados por frequência.

• Servidor de origem lento — Scripts PHP executando consultas complexas ao banco de dados, gerando relatórios ou chamando APIs de terceiros lentas podem exceder o timeout do proxy. Esta é a causa #1 dos erros 504.

• Sobrecarga do servidor — CPU a 100%, falta de memória (OOM kills) ou todos os workers do PHP-FPM ocupados. O servidor de origem está funcionando mas sobrecarregado demais para responder a tempo.

• Gargalo no banco de dados — Consultas SQL lentas, índices faltando, locks de tabelas ou pools de conexão esgotados. A aplicação trava esperando pelo banco de dados, e o proxy dá timeout.

• Valores de timeout mal configurados — proxy_read_timeout do Nginx configurado muito baixo para um backend que legitimamente precisa de mais tempo (ex: gerador de relatórios ou handler de upload de arquivos).

• Problemas de rede entre proxy e origem — Perda de pacotes, alta latência ou problemas de roteamento entre data centers. Comum em setups multi-região ou nuvem híbrida.

• Firewall ou security group bloqueando tráfego — Security groups da AWS não permitindo tráfego em portas efêmeras, regras de iptables bloqueando conexões internas ou WAF bloqueando requisições upstream legítimas.

• Falha de resolução DNS no proxy — O proxy não consegue resolver o hostname do upstream. No Nginx, isso acontece ao usar variáveis no proxy_pass sem uma diretiva resolver.

• Timeout do CDN — O Cloudflare tem um limite fixo de 100 segundos nos planos Free/Pro/Business. Se o seu servidor de origem demora mais que 100 segundos, o Cloudflare retorna Error 524 independentemente da sua configuração do Nginx.

• Ataque DDoS — Uma enxurrada de requisições esgota os recursos do servidor, tornando a origem lenta demais para responder ao tráfego legítimo dentro da janela de timeout do proxy.

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.

• Aguarde e atualize — A maioria dos erros 504 são temporários. Espere 30-60 segundos, depois force a atualização da página com Ctrl+Shift+R (Windows/Linux) ou Cmd+Shift+R (Mac).

• Verifique se o site está fora do ar para todos — Use a ferramenta de HTTP Headers do DNS Robot para verificar o código de resposta do servidor de uma localização externa. Se retornar 504 para todos, o problema é no servidor.

• Tente no modo anônimo ou outro navegador — Isso descarta extensões do navegador, páginas de erro em cache e problemas de configuração local.

• Tente uma rede diferente — Mude de Wi-Fi para dados móveis, ou desative seu VPN. Problemas de roteamento entre seu provedor de internet e o servidor podem às vezes causar 504.

• Limpe seu cache DNS — Registros DNS desatualizados podem direcionar requisições para o servidor errado. No Windows: ipconfig /flushdns. No Mac: sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder.

• Verifique a página de status ou redes sociais do site — O site pode ter publicado sobre uma queda conhecida ou janela de manutenção.

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_connect_timeout 300;
    proxy_send_timeout    300;
    proxy_read_timeout    300;
    send_timeout          300;
}

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

Para Apache com mod_proxy, adicione ProxyTimeout 300 no seu VirtualHost ou use ProxyPass / http://backend:8080/ timeout=300 para configuração por backend.

Importante: Esses timeouts medem o tempo entre duas operações de leitura/escrita consecutivas, não o tempo total de transferência. Então proxy_read_timeout 300 significa "se nenhum dado chegar por 300 segundos", não "a resposta inteira deve ser concluída em 300 segundos." Após alterar os valores de timeout, recarregue a configuração: sudo nginx -t && sudo systemctl reload nginx.

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.2-fpm.log

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

Mensagens comuns nos logs que causam 504:

"upstream timed out (110: Connection timed out)" (Nginx) — O servidor upstream não respondeu dentro do proxy_read_timeout. Aumente o timeout ou corrija o upstream lento.

"server reached pm.max_children" (PHP-FPM) — Todos os processos worker do PHP estão ocupados. Aumente pm.max_children na configuração do pool PHP-FPM.

"connect() failed (111: Connection refused)" (Nginx) — O servidor upstream não está rodando ou não está escutando na porta esperada. Reinicie o backend.

"Too many connections" (MySQL) — O limite de conexões do banco de dados foi esgotado. Aumente max_connections na configuração do MySQL ou otimize o pool de conexões.

Correção 5: Ajustar Configurações do PHP-FPM

Após alterar as configurações do PHP-FPM, reinicie o serviço: sudo systemctl restart php8.2-fpm. Garanta que o fastcgi_read_timeout do Nginx seja sempre maior ou igual ao max_execution_time do PHP. Caso contrário, o Nginx desiste antes do PHP terminar, criando um erro 504.

Correção 6: Verificar Configuração do CDN e Proxy

Usuários do Cloudflare: Se você está em um plano Free, Pro ou Business e seu servidor de origem demora mais de 100 segundos, você sempre receberá Error 524. As únicas opções são: otimizar seu backend para responder em até 100 segundos, mover tarefas demoradas para jobs em segundo plano, ou fazer upgrade para Enterprise.

Usuários do AWS CloudFront: Aumente o timeout de resposta de origem nas configurações de origem da sua distribuição. O padrão de 30 segundos geralmente é muito baixo para conteúdo dinâmico.

Use a ferramenta de HTTP Headers do DNS Robot para verificar os cabeçalhos de resposta e identificar qual camada está retornando o 504. Procure por cabeçalhos como server: cloudflare, server: awselb/2.0 ou server: nginx para identificar o proxy.

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.

• Aumente a memória PHP — Adicione define('WP_MEMORY_LIMIT', '512M'); ao wp-config.php. Muitos plugins precisam de mais que os 128MB padrão.

• 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.

• Desative o wp-cron — O cron virtual do WordPress roda em cada carregamento de página e pode acumular tarefas. Adicione define('DISABLE_WP_CRON', true); ao wp-config.php e configure um cron job real no servidor: */5 * * * * curl -s https://seusite.com/wp-cron.php > /dev/null 2>&1.

504 vs 502 vs 503 vs 408: Qual a Diferença?

A distinção crítica: o 502 significa que o proxy recebeu uma resposta ruim, enquanto o 504 significa que o proxy não recebeu nenhuma resposta. O 503 não requer um proxy — qualquer servidor pode retorná-lo quando sobrecarregado. O 408 é um timeout do lado do cliente (classe 4xx), onde o servidor desistiu de esperar pelo cliente.

Se você vê um 502 e um 504 ao mesmo tempo, o servidor upstream provavelmente está travando. O 502 ocorre quando o proxy recebe uma resposta parcial ou corrompida de um processo morrendo, e o 504 ocorre quando o processo está completamente sem resposta.

O Erro 504 Afeta o SEO?

Resposta curta: um 504 breve não tem impacto no SEO. Um 504 prolongado pode causar desindexação.

Minutos a horas: Sem impacto. O Google entende erros temporários de servidor e não penaliza imediatamente. Se o Googlebot não rastrear durante a queda, ele nem vai perceber.

Horas a dias: O Google reduz a frequência de rastreamento para sites que retornam erros 5xx para evitar sobrecarregar um servidor com problemas. As páginas podem aparecer como "Erro do servidor (5xx)" no relatório de Indexação de Páginas do Google Search Console.

Dias a semanas: Erros 504 persistentes podem levar à desindexação das páginas afetadas. Os rankings caem significativamente. Segundo John Mueller do Google: se um servidor fica fora do ar por um dia, as coisas podem ficar "em fluxo" por uma a três semanas após a recuperação.

Recuperação: Uma vez que o servidor está estável novamente, o Google re-rastreia e re-indexa as páginas automaticamente. Use a ferramenta de Inspeção de URL do Google Search Console para solicitar a reindexação de páginas importantes. O tempo de recuperação depende do tamanho do site e de quanto tempo os erros duraram.

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 — Use monitoramento de uptime (UptimeRobot, Pingdom ou a ferramenta Ping do DNS Robot) para detectar erros 504 antes que seus usuários reportem.

• 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.