De Olho

erro 504 gateway timeout

Erro 504: alguém desistiu de esperar pela resposta.

O 504 quase nunca é uma avaria. É lentidão que passou de um limite — e subir o limite é a tentação errada, porque transforma um erro rápido num site que demora um minuto a responder.

O servidor da frente fez o pedido ao de trás e ficou à espera. Passado o tempo configurado — costumam ser 60 segundos, às vezes 30 — desistiu e respondeu 504 ao visitante. O pedido pode até estar ainda a correr do outro lado; a diferença é que já ninguém está à espera dele.

A distinção em relação ao 502 é a que interessa: no 502 a ligação partiu-se ou a resposta era inválida; no 504 estava tudo bem, só demorou de mais. O que significa que o 504 é quase sempre um problema de desempenho disfarçado de erro.

É por isso que o 504 costuma aparecer primeiro nos sítios mais pesados — uma importação, uma exportação de encomendas, uma página de administração com muitos dados. O site público continua a abrir, e alguém chega ao pé de ti a dizer que "o site está bom, só o backoffice é que não". É o mesmo problema, apanhado mais cedo.

// a ficha

O que este código diz, em cinco linhas.

Código
504 Gateway Timeout
Família
5xx — erro do servidor
Quem responde
o proxy, a CDN ou o balanceador
Causa quase sempre
lentidão do lado de trás
Onde bate
primeiro no wp-admin, só depois no site

// causas prováveis

Por onde é que isto costuma vir.

Por ordem de frequência e não por ordem de gravidade. A primeira da lista explica mais casos do que as outras todas juntas.

  • Uma consulta à base de dados sem índice

    A causa mais comum em sites que cresceram. Uma consulta que corria em 40 ms com mil registos corre em 40 segundos com duzentos mil. Não mudou nada no código — mudaram os dados.

  • Um pedido a um serviço externo que não responde

    Uma API de pagamentos, um serviço de envio de emails, um plugin que consulta um servidor de licenças a cada carregamento. Se o serviço externo demora, o teu site demora — e o timeout é do teu proxy, não do deles.

  • Trabalho pesado a correr durante o pedido

    Importações de CSV, geração de PDFs, envio de newsletters, redimensionamento de imagens. Tudo isto devia correr em fila e não com um visitante à espera do outro lado.

  • Recursos partilhados esgotados

    Em alojamento partilhado, o vizinho conta. Quando a CPU da máquina está a 100%, tudo fica lento, e o que era um pedido de dois segundos passa a ser um de sessenta.

  • Timeouts mal casados entre camadas

    Se o Nginx desiste aos 60 segundos e o PHP está configurado para correr até 300, o Nginx corta primeiro e devolve 504 num processo que ainda estava a trabalhar. Os números têm de fazer sentido em conjunto.

// diagnóstico

Passo a passo, do que custa menos ao que custa mais.

Cada passo elimina hipóteses. Saltar um passo poupa dois minutos e costuma custar uma hora — a ordem é a parte que interessa.

  1. 01

    Mede o tempo de resposta antes de assumir o que quer que seja

    Verifica o site de fora e olha para o tempo em milissegundos. Um site saudável responde abaixo dos 600 ms; um que responde em 8 segundos está a caminho do 504 e ainda não lá chegou. É o mesmo problema, medido antes de rebentar.

  2. 02

    Descobre se é o site todo ou só uma página

    Se a página inicial abre e só o `/wp-admin/` ou uma página de listagem é que dá 504, o problema está numa consulta concreta. Isso muda tudo: não é o servidor, é uma coisa específica que ele faz.

  3. 03

    Vê se a lentidão é constante ou por picos

    Constante aponta para uma consulta lenta ou um serviço externo. Por picos, à mesma hora, aponta para um cron ou para o vizinho do alojamento partilhado. O registo de tempos de resposta ao longo de dias responde a isto; uma verificação isolada não responde.

  4. 04

    Desliga os plugins que falam para fora

    Estatísticas, anti-spam, sincronizações, verificadores de licença. Um de cada vez, e mede outra vez. É a forma mais rápida de encontrar o pedido externo que está a segurar tudo.

  5. 05

    Procura as consultas lentas

    O log de consultas lentas do MySQL diz-te exactamente quais são e quanto demoram. Em WordPress, o Query Monitor mostra o mesmo sem acesso ao servidor. É o passo que dá a resposta em vez de dar mais uma hipótese.

  6. 06

    Só depois disto é que faz sentido subir o timeout

    Subir de 60 para 300 segundos não corrige nada — só troca um erro por uma página que demora cinco minutos. Faz sentido para uma importação pontual, numa rota só. Como medida permanente para o site inteiro, é esconder o problema.

O primeiro passo é sempre o mesmo — ver de fora o que o servidor responde de facto. Faz isso aqui, a partir de um servidor em Portugal. Sem conta, sem custo, e não guardamos o que verificares.

verificar_site servidor: PT

// que não volte

Como evitar que volte a acontecer sem dares por isso.

Resolver o incidente é metade do trabalho. A outra metade é a parte que ninguém factura e é a que decide se há um terceiro.

  • Tira o trabalho pesado do caminho do visitante

    Filas, crons e processos em segundo plano existem para isto. Nenhum pedido de um visitante devia estar à espera de um PDF a ser gerado.

  • Põe timeout em tudo o que fala para fora

    Uma chamada a uma API externa sem timeout definido herda o do sistema, que é longo de mais. Cinco segundos e uma falha elegante é melhor do que sessenta e um 504.

  • Vigia o tempo de resposta e não só o estado

    Um site que passou de 200 ms para 1 400 ms ao longo de duas semanas não está em baixo, mas está a caminho. Quem só verifica se responde não vê nada até ao dia em que deixa de responder.

  • Trata a lentidão como um incidente e não como um feitio

    "O site é assim, é lento" é a frase que precede o 504. A degradação instala-se devagar o suficiente para toda a gente se habituar.

// limites

Onde é que esta página encalha.

Uma página de diagnóstico que não diz onde acaba manda-te dar voltas até desistires. Estes são os casos em que não chega.

  • Não conseguimos dizer qual é a consulta lenta a partir de fora. O tempo de resposta diz que há um problema e a partir de que dia; qual é a linha de SQL só se vê por dentro.
  • Um 504 numa rota específica pode não aparecer em nenhuma verificação da página inicial. Se o problema é o backoffice, é o backoffice que tem de ser vigiado.
  • Esta página não trata do desempenho percebido no browser — imagens pesadas, JavaScript a bloquear. Isso é outro assunto e mede-se com outras ferramentas.
  • Em alojamento partilhado, muita coisa aqui está fora do teu alcance. Se a CPU da máquina é do vizinho, o caminho acaba por ser mudar de plano ou de alojamento.

// perguntas

O que nos perguntam a seguir.

Devo aumentar o timeout do servidor?

Quase nunca como primeira medida. Um timeout maior transforma um erro rápido numa espera longa, e a experiência de quem visita piora em vez de melhorar. Faz sentido para uma rota concreta que tem mesmo de demorar — uma importação, por exemplo — e não para o site inteiro.

O 504 pode ser da Cloudflare e não do meu servidor?

Pode, e nesse caso a página de erro costuma ter a marca deles. Mas o mais comum é a Cloudflare estar a reportar honestamente que a tua origem demorou de mais. Testar directamente contra o IP de origem separa os dois casos.

Porque é que só o wp-admin dá 504?

Porque é a parte do site que não tem cache e que faz as consultas mais pesadas. É onde a lentidão aparece primeiro. Se o backoffice já dá 504, o site público está mais perto do que parece.

// erros vizinhos

Se afinal não era este.

Metade do diagnóstico é perceber que se estava a olhar para o erro errado. Estes três são os que mais se confundem com este.

E se acontecer às três da manhã?

O 504 tem um aviso prévio que quase ninguém aproveita: o tempo de resposta sobe durante dias antes de haver erro nenhum. A De Olho vai guardar esse número em cada verificação, o que faz aparecer no gráfico a subida que hoje só se nota quando o site já está a dar erro. Enquanto o produto não abre, dá para medir uma vez com a ferramenta gratuita — o que falta é ela repetir-se sozinha.

A De Olho abre em 2026 e ainda não dá para usar. Quem estiver na lista de espera fica a saber primeiro e mantém o preço de lançamento enquanto a subscrição durar.

Só te escrevemos sobre o lançamento. Sem spam, e não partilhamos o teu email com ninguém. Como tratamos os teus dados.