Como corrigir o erro 504 Gateway Timeout (7 soluções)

O erro 504 Gateway Timeout ocorre quando um servidor que atua como gateway ou proxy não recebe a tempo uma resposta de outro servidor. Isso geralmente acontece quando a aplicação de backend de um site está lenta, sobrecarregada ou com problemas de conectividade.

Se você está acessando um site, tente atualizar a página após alguns instantes. Se você administra o site, comece verificando os logs do servidor e da aplicação para identificar onde ocorre o atraso.

Veja sete maneiras práticas de investigar o erro.

O que causa o erro 504 Gateway Timeout?

Muitos sites usam vários servidores ou serviços para processar solicitações.

Por exemplo, um navegador pode se conectar ao Nginx ou a uma CDN, que então encaminha a solicitação para um servidor de aplicação.

Se essa aplicação demorar demais para responder, o gateway poderá retornar um erro 504 em vez da página solicitada.

As causas comuns incluem:

• Servidores de aplicação sobrecarregados ou que não respondem.
• Consultas lentas ao banco de dados ou solicitações a APIs externas.
• CPU, RAM ou processos de trabalho da aplicação insuficientes.
• Problemas de rede entre o gateway e o backend.
• Limites de tempo de resposta do proxy ou da aplicação.
• CDN ou infraestrutura de hospedagem configurada incorretamente.

Um erro 504 geralmente é um problema do lado do servidor, embora problemas específicos de conexão possam, às vezes, afetar visitantes individualmente.

1. Atualize o site e verifique se ele está disponível

Se você está apenas acessando um site, aguarde um pouco e atualize a página.

Uma sobrecarga temporária do servidor ou uma solicitação interrompida ao backend pode se resolver sem intervenção.

Você também pode tentar outro navegador ou outra rede para verificar se o problema é específico da sua conexão.

Se o erro afetar todas as pessoas, o proprietário do site ou o provedor de hospedagem geralmente precisará investigar.

Evite enviar pagamentos, pedidos ou formulários repetidamente. Uma operação no backend pode ter sido concluída mesmo que o gateway tenha excedido o tempo limite antes de retornar a resposta.

2. Verifique os logs do servidor e da aplicação

Se você administra o servidor, os arquivos de log são o melhor ponto de partida.

No Nginx, verifique o log de erros:

sudo tail -n 50 /var/log/nginx/error.log

Procure mensagens semelhantes a:

upstream timed out (110: Connection timed out)

Isso indica que o Nginx esperou tempo demais por uma operação do servidor upstream.

Em seguida, verifique os logs da aplicação para descobrir por que o backend demorou a responder.

Você também pode verificar um serviço gerenciado pelo systemd:

sudo journalctl -u myapp -n 50

Substitua myapp pelo nome real do seu serviço.

3. Verifique o uso de CPU, RAM e disco

Um servidor sobrecarregado pode ter dificuldade para processar solicitações dentro do tempo limite do gateway.

Verifique a memória:

free -h

Verifique o espaço em disco:

df -h

Monitore os processos:

top

Procure sinais de sobrecarga contínua de recursos, memória esgotada, sistemas de arquivos cheios ou processos com atividade anormalmente alta.

Esses resultados não comprovam, por si só, por que a solicitação excedeu o tempo limite, mas podem ajudar a identificar gargalos de desempenho.

4. Investigue os tempos limite do Nginx e dos servidores upstream

Se o Nginx atua como proxy reverso, verifique se a aplicação upstream responde dentro dos limites de tempo configurados.

Para backends HTTP, uma configuração pode incluir:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_read_timeout 60s;
}

A configuração proxy_read_timeout controla por quanto tempo o Nginx espera entre leituras sucessivas do backend, e não a duração total da solicitação.

Antes de aumentar esse valor, teste o backend diretamente:

curl --max-time 15 -i http://127.0.0.1:3000/

Substitua o endereço pelo endpoint real da sua aplicação. Algumas rotas da aplicação podem exigir autenticação ou retornar uma resposta válida diferente de HTTP 200.

Se a própria aplicação estiver lenta, aumentar o tempo limite do Nginx pode apenas ocultar o problema subjacente.

Quando um tempo limite maior for realmente necessário, revise também as configurações de tempo limite da aplicação. Aplicações baseadas em PHP-FPM e FastCGI usam diretivas do Nginx diferentes das usadas por backends com proxy HTTP.

Após alterar a configuração, valide o Nginx antes de recarregá-lo:

sudo nginx -t
sudo systemctl reload nginx

Recarregue-o somente se o teste de configuração for bem-sucedido.

5. Verifique o Cloudflare ou sua CDN

Se o seu site usa o Cloudflare ou outra rede de distribuição de conteúdo, determine se o tempo limite é excedido na CDN ou no seu servidor de origem.

Verifique as informações de erro da sua CDN e compare-as com os logs do servidor de origem.

Um erro 504 pode vir de um serviço upstream por trás do servidor de origem ou de outra camada no caminho da solicitação.

O Cloudflare tem seus próprios limites de tempo para conexão e resposta. Por isso, aumentar uma configuração do Nginx não necessariamente elimina um limite imposto pela CDN.

Evite desativar recursos de segurança ou cache sem identificar a origem do problema de tempo limite.

6. Investigue consultas lentas ao banco de dados e APIs externas

Às vezes, o servidor web está funcionando normalmente, mas a aplicação está aguardando outro serviço.

Exemplos comuns incluem:

• Uma consulta ao banco de dados que demora demais.
• Uma API externa que demora a responder.
• Pools de processos de trabalho da aplicação esgotados.
• Tarefas em segundo plano competindo por recursos.
• Bloqueios no banco de dados que atrasam as solicitações.

Analise os logs da aplicação, os logs de consultas lentas e as métricas dos serviços para identificar o atraso.

Se a causa for uma consulta ao banco de dados, investigue a indexação, os planos de execução de consultas e o uso de conexões.

Para chamadas a APIs externas, configure tempos limite razoáveis e um tratamento adequado de erros. Quando a aplicação oferece suporte a isso, pode ser melhor executar tarefas demoradas de forma assíncrona.

7. Entre em contato com seu provedor de hospedagem

Se você não conseguir resolver o erro 504 Gateway Timeout, entre em contato com seu provedor de hospedagem e apresente as informações que coletou.

Informe o domínio afetado, quando o problema começou, se ocorre de forma intermitente e quaisquer mensagens de log relevantes.

Mencione alterações recentes na aplicação, no banco de dados, na CDN ou na configuração do proxy reverso.

O provedor de hospedagem pode ajudar a investigar restrições de recursos e problemas de infraestrutura fora do seu alcance administrativo.

Erros 502 e 504 de gateway: qual é a diferença?

Esses erros estão relacionados, mas indicam problemas diferentes nos servidores upstream.

Por exemplo, uma aplicação que encerra uma conexão inesperadamente pode causar um erro 502, enquanto uma aplicação que demora demais para responder pode causar um erro 504.

Como evitar erros 504 Gateway Timeout

Nem todos os problemas de tempo limite podem ser evitados, mas uma boa gestão da infraestrutura ajuda a reduzi-los.

• Monitore os tempos de resposta da aplicação e o uso de recursos.
• Investigue consultas lentas ao banco de dados.
• Use um cache adequado para conteúdos solicitados com frequência.
• Configure limites de tempo adequados para os servidores upstream e a aplicação.
• Monitore os serviços de backend e a disponibilidade dos processos de trabalho.
• Teste alterações importantes de configuração antes de colocá-las em produção.

Aumentar os limites de tempo deve ser uma decisão ponderada, não o primeiro passo da investigação.

Perguntas frequentes

Conclusão

O erro 504 Gateway Timeout significa que um gateway esperou tempo demais pela resposta de um servidor upstream.

Os visitantes podem verificar se o problema é temporário, enquanto os administradores devem examinar logs, recursos do servidor, desempenho da aplicação e configurações de proxy.

A solução mais confiável é identificar a origem do atraso, em vez de aumentar os limites de tempo ou reiniciar serviços sem antes investigar a causa.