O que significa um 504 Gateway Timeout? E de quem é a culpa

Um 504 Gateway Timeout significa que um servidor pelo meio pediu algo a outro servidor e desistiu de esperar. A página que queria existe. A máquina que a teria construído não respondeu a tempo, e a máquina à frente dela deixou de segurar a porta aberta.

Se é visitante: não é o seu computador, não é o seu navegador e não é a sua ligação. Todo o código de erro que começa por 5 é o próprio site a comunicar um problema seu. Limpar a cache não vai ajudar, e experimentar outro navegador também não.

A imagem dos dois servidores

Quase nenhum site é uma só máquina. Um pedido chega normalmente a algo que está à frente - um balanceador de carga, um proxy inverso, um nó de CDN - e essa coisa passa-o para aquilo que executa de facto a aplicação, e depois devolve-lhe a resposta.

Um 504 é o relato da máquina da frente sobre a de trás: perguntei, esperei, não veio nada, aqui tem um código de estado para não ficar a olhar para um separador vazio. A aplicação do site nunca teve oportunidade de lhe dizer nada, e é por isso que uma página de 504 costuma parecer genérica em vez de se parecer com o site à volta.

Isso explica também os tempos. Um 504 costuma chegar depois de uma pausa longa - dez segundos, trinta, sessenta - porque a pausa é o ponto. Alguma coisa ainda estava a tentar.

504 contra 502, que são constantemente confundidos

Vêm do mesmo sítio e significam coisas diferentes, e saber qual deles tem estreita bastante a causa.

502 Bad Gateway

O servidor a montante respondeu, e a resposta era inutilizável - uma ligação recusada, um processo que rebentou, lixo no fio. Normalmente rápido

504 Gateway Timeout

O servidor a montante não respondeu de todo dentro do tempo permitido. Normalmente lento, e o atraso antes do erro é por si só uma pista

Grosso modo: 502 é “disse alguma coisa errada”, 504 é “ainda não disse nada”. Um 502 aponta para algo partido ou em baixo; um 504 aponta para algo lento, encravado ou sobrecarregado.

Uma subtileza que vale a pena conhecer, porque a maioria dos artigos a deixa passar: alguns fornecedores usam códigos próprios para isto. A Cloudflare devolve 524 quando a sua origem aceita uma ligação e depois demora demasiado a responder, que é a mesma história contada por outra camada. Se está atrás de uma CDN, o número que recebe pode ser o deles em vez do padrão.

Se é o visitante

Há muito pouco a fazer, e essa é a resposta honesta mais do que uma resposta curta.

Espere um minuto e recarregue. Um 504 é muitas vezes passageiro - uma consulta lenta, um processo a reiniciar, um pico de tráfego. Se persistir, veja se o serviço tem uma página de estado ou se mais alguém o está a reportar, porque a falha é do lado deles e só eles a podem resolver.

A única coisa genuinamente útil que pode fazer é dizer-lhes, com detalhe suficiente para que a consigam encontrar. Que página, a que horas e o que estava a fazer. Um 504 num pagamento às 14:32 é algo que um engenheiro pode ir procurar num registo; “o vosso site não funciona” não é.

Se o site é seu

Quatro causas explicam a maioria deles, mais ou menos por esta ordem.

• Uma coisa lenta. Uma consulta à base de dados sem índice, uma API externa que chama enquanto o utilizador espera, um relatório que cresceu para além do tamanho para que foi pensado. O pedido não está encravado, apenas é mais lento do que a paciência do proxy.
• Um tempo limite abaixo da realidade. O Nginx usa por omissão sessenta segundos para uma leitura encaminhada. Se o seu pedido legítimo mais lento demora noventa, vai servir 504 às pessoas que usam a funcionalidade que mais importa.
• Workers esgotados. Todos os processos da aplicação estão ocupados, por isso os pedidos novos ficam na fila atrás deles e nem chegam ao código. Este aparece aos surtos e parece o site a cair por inteiro, porque na prática é o que acontece.
• O caminho de rede. Um grupo de segurança, uma alteração de DNS, um serviço que mudou de sítio. Menos comum, e normalmente total em vez de intermitente.

Descubra que camada o emitiu antes de mudar seja o que for. O registo de acessos do próprio proxy guarda o estado que devolveu e quanto tempo esperou; o registo da aplicação mostrará ou um pedido que demorou esse tempo ou nada de nada para aquele momento. Estes dois casos têm correções opostas, e adivinhar entre eles é como as pessoas acabam a subir um tempo limite que nunca foi o problema.

Subir o tempo limite é a jogada tentadora e, por si só, costuma estar errada. Transforma uma falha rápida numa lenta e move a fila para outro sítio. É a jogada certa apenas quando sabe que o trabalho demora legitimamente esse tempo e não pode ser tornado assíncrono.

Porque são tão difíceis de perseguir mais tarde

Um 504 é um momento. Quando alguém o menciona, a consulta lenta já terminou, os workers já esvaziaram, o surto já passou, e a página carrega perfeitamente quando experimenta.

Por isso o relato chega como “esteve avariado há bocado” e não há nada para ver. O que o tornaria localizável é o que o navegador viu na altura: que pedido excedeu o tempo, contra que host, quanto esperou e o que mais na página já tinha falhado. Isso está no painel de rede enquanto está a acontecer e desaparece no momento em que o separador é fechado.

É esse o argumento para o capturar no momento em vez de o descrever depois - um ficheiro HAR é a forma habitual de o fazer à mão, e é exatamente o que o registo de rede de um relatório de erro transporta. As mesmas provas respondem à outra pergunta que vale a pena fazer cedo, que é se o tempo limite foi do seu serviço ou do de outra pessoa: a coluna do host diz qual.

Num parágrafo

Um 504 significa que o servidor da frente perguntou ao servidor de trás e ficou sem paciência. É problema do site e não seu, normalmente quer dizer lento em vez de partido, e distingue-se de um 502 pela pausa que o antecede. Se o site é seu, descubra que camada excedeu o tempo antes de mexer em qualquer definição de tempo limite, porque o registo que não guardou nada e o registo que guardou noventa segundos estão a contar-lhe duas histórias diferentes.