HTTPTools

HTTP 504 Gateway Timeout

L'intermediario ha smesso di aspettare: il server upstream non ha risposto entro il limite di tempo del proxy.

Cosa significa HTTP 504

HTTP 504 Gateway Timeout viene emesso da un proxy, un load balancer o una CDN la cui richiesta al server upstream non ha ricevuto risposta entro il proprio timeout. A differenza del 502 — dove l'upstream ha risposto male — con 504 non ha risposto affatto in tempo.

La causa profonda è quasi sempre qualcosa di lento dietro le quinte: una query al database costosa, un'API esterna che non risponde, o un pool di thread dell'applicazione sotto pressione per il carico.

Cause comuni degli errori 504

  • Una query al database lenta o un indice mancante che fa impiegare a un endpoint più tempo di quanto il proxy consenta.
  • L'applicazione che attende un'API esterna che è essa stessa lenta o inattiva.
  • Backend saturo: tutti i worker occupati, richieste in coda oltre il timeout.
  • Problemi di rete tra proxy e upstream (routing, perdita di pacchetti, DNS).
  • Discrepanza di timeout: l'app ha legittimamente bisogno di 60s, il proxy taglia a 30s.

Come risolverlo da visitatore

  • Riprova dopo un momento — un singolo 504 è spesso solo una richiesta lenta, non un'interruzione.
  • Per un'azione che hai inviato (pagamento, ordine), controlla se è effettivamente andata a buon fine prima di riprovare.

Come risolverlo da sviluppatore

  • Trova l'endpoint lento nei log di accesso/APM: sistema la query, aggiungi indici, metti in cache il risultato.
  • Sposta i lavori lenti in job in background e rispondi rapidamente con uno stato che il client può interrogare.
  • Allinea i budget di timeout end to end (app < proxy < CDN) così l'anello più lento è noto e intenzionale.
  • Aggiungi circuit breaker attorno alle API esterne instabili invece di lasciare che blocchino i tuoi worker.

Esempio di risposta

HTTP/1.1 504 Gateway Timeout
Server: nginx
Content-Type: text/html

<html><body><h1>504 Gateway Timeout</h1></body></html>

FAQ

Qual è la differenza tra 504 e 502?

504 significa che l'upstream non ha mai risposto entro il timeout; 502 significa che ha risposto con qualcosa di non valido.

Un 504 è un problema di connessione dell'utente?

No — è tra il proxy del sito e il suo backend. La rete dell'utente va bene.

La mia richiesta inviata è stata elaborata se ho ricevuto un 504?

Possibilmente sì — il timeout ha colpito la risposta, non necessariamente l'elaborazione. Controlla lo stato prima di riprovare alla cieca azioni non idempotenti.