504 Gateway Timeout atrás do Cloudflare

O que este erro significa e como reconhecê-lo

• A página de erro tem a identidade visual do Cloudflare e geralmente inclui um Cloudflare Ray ID, em vez do layout de erro normal do seu site.
• Um relatório, exportação, upload, chamada de API ou ação em massa específico falha enquanto as páginas comuns continuam carregando.
• A mesma requisição pode responder lentamente, atingir o timeout ou falhar quando testada diretamente na origem.
• O problema pode ser intermitente quando a origem está sobrecarregada ou consistente quando o Cloudflare não consegue alcançar a origem configurada.
• Os logs da aplicação ou do servidor web podem mostrar que a requisição foi iniciada, mas não concluída antes do timeout apresentado ao cliente.

Causas principais, por probabilidade

1. A origem está demorando demais. Uma consulta ao banco de dados, relatório, exportação, upload ou outra operação síncrona pode exceder o tempo que o Cloudflare aguarda.
2. A requisição atinge um limite de timeout do Cloudflare. O limite aplicável depende da requisição, da configuração da conta e do plano. Aumentar o timeout do servidor web de origem não estende o limite da edge do Cloudflare.
3. O Cloudflare não consegue alcançar a origem de forma confiável. Regras de firewall, falhas de rede, um destino DNS incorreto, um serviço indisponível ou saturação de conexões podem impedir uma resposta em tempo hábil.
4. O endpoint não é adequado para proxy. Uma API interna ou especializada pode exigir um design DNS-only cuidadosamente controlado, em vez de passar pelo proxy do Cloudflare.
5. As configurações de SSL/TLS não correspondem à origem. Ao usar Full (strict), verifique o certificado da origem, o hostname e a validade do certificado. Problemas de certificado podem produzir outros erros de origem do Cloudflare; por isso, confirme a resposta exata em vez de presumir que todo problema de SSL é um 504.

Como corrigir

1. Confirme que o Cloudflare produziu a resposta

Verifique se a página de erro tem a identidade visual do Cloudflare e um Ray ID, depois compare-a com a página de erro normal da sua aplicação. Se a página foi gerada pelo Cloudflare, alterar apenas o tratamento de erros da aplicação não resolverá o problema entre a edge e a origem.

2. Defina o escopo e o momento do problema

Registre o hostname e o caminho exatos, o método HTTP, a ação do usuário, o horário aproximado de início e se o problema afeta todos os visitantes ou uma operação específica. Verifique se as páginas comuns funcionam enquanto um relatório, exportação ou requisição de API falha.

Uma falha limitada a uma única operação cara aponta mais fortemente para a duração do processamento no backend. Falhas em requisições comuns e rápidas apontam mais fortemente para acessibilidade, capacidade ou configuração da origem.

3. Teste a origem de forma independente

Faça um teste direto autorizado na origem que preserve o hostname necessário, o cabeçalho Host, o comportamento de TLS, a autenticação e o roteamento. Um hostname temporário em DNS-only pode ser útil se for configurado com segurança e o acesso à origem continuar devidamente restrito.

• A origem também está lenta ou falha: verifique os logs da aplicação, consultas ao banco de dados, capacidade dos workers, dependências upstream, carga do servidor e saturação de conexões.
• A origem é rápida, mas o hostname público retorna 504: investigue o acesso do firewall entre o Cloudflare e a origem, o DNS, as configurações de SSL/TLS, o status do proxy e o endpoint afetado.
• O teste direto não é representativo: repita-o com a mesma autenticação, roteamento baseado em hostname, cabeçalhos e outros requisitos usados pela requisição que falha.

4. Corrija uma operação realmente lenta

Para um relatório, exportação, ação em massa ou outra tarefa de longa duração, evite manter uma única requisição do navegador aberta até a conclusão de todo o trabalho. Mova a operação para um job em segundo plano, exiba um estado de processamento e permita que o usuário obtenha o resultado por polling ou por uma notificação de conclusão.

Também meça as consultas ao banco de dados, os traces da aplicação, as chamadas upstream, a profundidade da fila e o uso de recursos. Não trate o aumento do timeout da origem como correção principal sem medir a operação: se o Cloudflare atingir o limite primeiro, o visitante continuará recebendo um erro enquanto a origem pode continuar executando trabalho desnecessário.

5. Verifique o timeout aplicável do Cloudflare

Consulte a conta do Cloudflare e a documentação relevante para verificar o timeout aplicável à requisição e ao plano afetados. Se o trabalho for válido, mas não puder ser concluído dentro de um limite fixo, as opções práticas são redesenhá-lo como trabalho assíncrono ou usar uma configuração de conta e um plano que ofereçam suporte ao timeout necessário, quando disponível.

6. Verifique a acessibilidade quando as falhas forem persistentes

Se requisições comuns e rápidas também falharem, verifique:

• O registro DNS aponta para o endereço atual da origem.
• O firewall da origem permite o tráfego do Cloudflare conforme necessário, sem expor serviços desnecessários.
• O servidor web está escutando na porta esperada e aceita o hostname solicitado.
• A origem tem capacidade suficiente e não está descartando ou enfileirando conexões.
• O modo de SSL/TLS corresponde ao certificado, hostname e validade do certificado da origem, especialmente com Full (strict).
• O registro afetado deve usar proxy, em vez de ser servido por uma configuração DNS-only controlada.

Faça alterações de DNS, firewall, SSL/TLS ou proxy somente com a autorização adequada e um plano de rollback. Teste novamente o endpoint exato que falha após cada alteração relevante, para manter clara a relação entre causa e efeito.

7. Escale o problema com evidências úteis

Se a origem estiver saudável e responder rapidamente por meio de um teste direto equivalente, reúna o Ray ID, o horário e o fuso horário, o hostname, o caminho, o método da requisição, a zona do Cloudflare afetada e os resultados do teste direto. Forneça essas informações ao administrador da conta do Cloudflare ou ao contato de suporte para que o comportamento entre a edge e a origem possa ser investigado.

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

• Meça o tempo de resposta da origem e a duração total da requisição separadamente da disponibilidade observada pelo Cloudflare.
• Coloque relatórios, exportações, uploads e operações em massa previsivelmente demorados em jobs em segundo plano, com progresso visível ou status de conclusão.
• Crie alertas para aumento da latência da origem, falhas de conexão, saturação de recursos e profundidade da fila antes que os usuários encontrem timeouts.
• Mantenha registros DNS, regras de firewall da origem e allowlists de tráfego do Cloudflare sob controle de mudanças.
• Monitore a validade do certificado da origem e a cobertura de hostnames ao usar Full (strict), e revise as alterações de SSL/TLS antes da implantação.
• Documente quais endpoints devem usar o proxy do Cloudflare e quais exigem um design DNS-only controlado.
• Teste novamente a conectividade representativa com a origem após alterações de infraestrutura, DNS, firewall, certificado ou proxy.

Perguntas frequentes