504 Gateway Timeout

O que este erro significa e como reconhecê-lo

• O navegador exibe 504 Gateway Timeout depois de aguardar, em vez de falhar imediatamente.
• Relatórios, importações em massa, exportações, processamento de imagens ou pesquisas complexas falham, enquanto páginas simples continuam funcionando.
• As falhas se tornam mais frequentes quando a aplicação está ocupada ou as requisições ficam em fila.
• O backend responde quando testado diretamente, mas a mesma requisição sofre timeout através de um proxy, CDN ou balanceador de carga.
• Os logs do gateway mostram uma requisição upstream de longa duração antes do retorno do 504.
• A aplicação pode continuar processando depois que o navegador recebeu o timeout, potencialmente deixando trabalho duplicado ou abandonado se a ação for repetida.

Causas principais, por probabilidade

1. Consultas lentas ou bloqueadas ao banco de dados: Índices ausentes, tabelas maiores, consultas ineficientes e contenção de locks podem fazer a aplicação aguardar além do limite do gateway.
2. Sobrecarga ou enfileiramento no backend: As requisições podem estar aguardando workers da aplicação, conexões com o banco de dados, CPU, memória ou outros recursos limitados.
3. Uma operação síncrona genuinamente demorada: Exportações, importações, relatórios ou processamento de arquivos grandes podem ser válidos, mas inadequados para uma requisição de página comum.
4. Uma API downstream ou um webhook lento: A aplicação pode estar aguardando outro serviço antes de responder.
5. Timeouts restritivos no proxy ou servidor: Nginx, Apache, uma CDN ou um balanceador de carga pode parar de aguardar antes que a aplicação termine.
6. Problemas de rede entre camadas do gateway: Latência, perda intermitente de pacotes ou falhas de roteamento são mais prováveis em implantações com vários servidores ou regiões, especialmente quando o tempo da aplicação não explica o atraso.

Como corrigir

1. Identifique a requisição com falha e sua duração

Verifique os logs de acesso do gateway e da aplicação em busca da requisição que produziu o 504. Registre a rota ou ação do usuário, o timestamp, a duração da resposta, o status e se todas as requisições falham ou apenas uma operação.

Se apenas relatórios, importações, exportações ou pesquisas complexas falham, comece por essa operação em vez de tratar o incidente como uma indisponibilidade completa do servidor.

2. Compare o backend com o caminho completo da requisição

Com autorização e uma requisição de teste segura, compare o tempo de resposta direto do backend com o da mesma requisição através do proxy, CDN ou balanceador de carga.

• Uma resposta lenta tanto diretamente quanto através do gateway aponta para a aplicação, o banco de dados, a capacidade ou uma dependência.
• Uma resposta direta rápida, mas uma requisição com falha através do proxy, aponta para um timeout do intermediário, um problema de roteamento ou uma falha de rede entre o gateway e o backend.

Não contorne os controles de acesso de produção nem envie uma requisição que altere estado apenas para fins de teste.

3. Investigue o tempo das consultas e as esperas por locks

Ative ou consulte os diagnósticos de consultas lentas e esperas por locks do banco de dados de acordo com as orientações operacionais da plataforma de banco de dados. Procure consultas executadas próximas ou além do timeout ativo do gateway.

Verifique a ausência de índices, joins ou filtros ineficientes, o crescimento das tabelas e a contenção de locks. Otimize a consulta, reduza os dados processados ou adicione um índice somente depois de confirmar que isso resolve o gargalo medido. Coordene alterações de schema ou índices com o responsável pelo banco de dados, pois elas podem consumir recursos e afetar cargas de trabalho concorrentes.

Não aumente o timeout simplesmente para ocultar uma consulta que deveria ser concluída rapidamente.

4. Verifique a capacidade e as filas do backend

Revise as métricas da aplicação, do web server e do sistema em busca de esgotamento de workers, requisições enfileiradas, limites de conexões do banco de dados, pressão de CPU ou memória e outras restrições de recursos durante a falha.

Se as requisições estiverem aguardando capacidade, resolva esse gargalo antes de aumentar os timeouts. Alterar configurações de capacidade ou de processos pode afetar a estabilidade do serviço; faça essas alterações conforme a autorização operacional e o processo de mudança aplicáveis.

5. Mova o trabalho demorado para um job em segundo plano

Para importações, exportações, geração de relatórios, processamento de e-mails e tarefas semelhantes, use um job em segundo plano quando a aplicação oferecer suporte. A requisição inicial deve iniciar ou enfileirar o trabalho, enquanto uma tela de status separada ou uma notificação informa o progresso e a conclusão.

Isso evita manter aberta uma conexão do navegador, um worker do gateway e uma requisição da aplicação durante toda a operação. Garanta que o job tenha tratamento adequado para novas tentativas e envios duplicados antes de habilitar esse padrão.

6. Revise cuidadosamente as configurações de timeout do Nginx

Se o Nginx for o gateway, revise as configurações aplicáveis de proxy_read_timeout e proxy_connect_timeout no bloco server ou location relevante. Confirme qual camada está impondo o timeout antes de alterar qualquer coisa.

Aumente um timeout somente quando se espera que a operação demore mais, o backend estiver saudável e o uso adicional de conexões e workers for aceitável. Alterações de configuração exigem autorização adequada. Depois de salvar a alteração, valide a configuração e recarregue o Nginx de acordo com o procedimento normal de implantação; em seguida, repita a operação que falhava. Não combine o reload de um serviço com diagnósticos somente de leitura em uma alteração não planejada.

7. Revise as configurações de proxy do Apache

No Apache usando mod_proxy, revise as configurações aplicáveis de Timeout e ProxyTimeout. Se houver uploads grandes, revise também o comportamento relevante de mod_reqtimeout.

Quando possível, aplique a alteração segura mais restrita à rota ou operação afetada, com autorização e um plano de rollback. Teste novamente usando a mesma requisição e confirme que esperas mais longas não estão esgotando workers ou conexões.

8. Verifique o comportamento da CDN e do balanceador de carga

Se o site usar Cloudflare ou outra CDN ou balanceador de carga, revise o timeout do gateway, o roteamento para a origem, a integridade e a configuração no nível do plano desse serviço. Um intermediário pode impor um limite que não pode ser aumentado na configuração disponível.

Quando a origem precisar de mais tempo do que esse limite, otimize a operação ou mova-a para o processamento assíncrono em vez de depender de uma requisição de navegador mais longa.

9. Isole as chamadas lentas de terceiros

Meça separadamente cada chamada de API externa ou webhook. Defina um timeout interno menor para uma dependência, quando houver suporte, trate a falha explicitamente e retorne um estado pendente ou que permita nova tentativa quando o trabalho puder ser concluído depois.

Evite permitir que uma dependência não confiável consuma todo o timeout do gateway. Confirme que as novas tentativas são limitadas e seguras antes de adicionar um comportamento automático de retry.

10. Verifique a correção

Repita exatamente a ação da página ou a requisição que falhou anteriormente. Confirme que ela é concluída dentro do timeout ativo do gateway e inspecione os logs depois para garantir que o backend não esteja acumulando trabalho abandonado, duplicado ou com duração incomum. Teste através do caminho completo de produção, não apenas diretamente contra o backend.

Prevenção e como verificar a correção

• Use jobs em segundo plano para importações, exportações, geração de relatórios, processamento de e-mails e outros trabalhos que possam exceder a duração de uma requisição de página normal.
• Revise índices e planos de execução das operações de banco de dados por trás de páginas que frequentemente sofrem timeout à medida que os dados crescem.
• Monitore separadamente a duração da requisição, o tempo em fila, o tempo do banco de dados, o uso de workers e o tempo das dependências.
• Configure deliberadamente os timeouts do proxy e da aplicação para a operação legítima mais lenta, mantendo limitados os timeouts das dependências de terceiros.
• Teste operações críticas através do caminho completo de produção, incluindo a CDN ou o balanceador de carga, em vez de testar apenas contra a origem.
• Projete retries e novos envios de forma segura para que um timeout do gateway não crie jobs ou transações duplicados.
• Depois de uma alteração, repita exatamente a operação que sofreu timeout e confirme que ela é concluída sem acumular trabalho excessivo na fila.

Perguntas frequentes