Un 504 Gateway Timeout significa che un server in mezzo ha chiesto qualcosa a un altro server e ha smesso di aspettare. La pagina che volevi esiste. La macchina che l’avrebbe costruita non ha risposto in tempo, e la macchina davanti a lei ha smesso di tenere la porta aperta.

Se sei un visitatore: non è il tuo computer, non è il tuo browser e non è la tua connessione. Ogni codice di errore che inizia con 5 è il sito stesso che segnala un problema suo. Svuotare la cache non servirà, e nemmeno provare un altro browser.

L’immagine a due server

Quasi nessun sito è una macchina sola. Una richiesta di solito arriva a qualcosa che sta davanti - un bilanciatore di carico, un reverse proxy, un nodo di CDN - e quel qualcosa la passa a ciò che esegue davvero l’applicazione, poi ti inoltra la risposta.

Un 504 è il resoconto della macchina davanti su quella dietro: ho chiesto, ho aspettato, non è arrivato niente, ecco un codice di stato così non resti a fissare una scheda vuota. L’applicazione del sito non ha mai avuto occasione di dirti nulla, ed è per questo che una pagina 504 di solito sembra generica invece di somigliare al sito attorno.

Questo spiega anche i tempi. Un 504 di solito arriva dopo una lunga pausa - dieci secondi, trenta, sessanta - perché la pausa è il punto. Qualcosa ci stava ancora provando.

504 contro 502, che vengono confusi di continuo

Vengono dallo stesso posto e significano cose diverse, e sapere quale dei due hai restringe parecchio la causa.

502 Bad Gateway
Il server a monte ha risposto, e la risposta era inutilizzabile - una connessione rifiutata, un processo andato in crash, spazzatura sul filo. Di solito veloce
504 Gateway Timeout
Il server a monte non ha risposto affatto entro il tempo concesso. Di solito lento, e il ritardo prima dell'errore è già di per sé un indizio

In breve: 502 vuol dire “ha detto qualcosa di sbagliato”, 504 vuol dire “non ha ancora detto niente”. Un 502 indica qualcosa di rotto o spento; un 504 indica qualcosa di lento, bloccato o sovraccarico.

Una sottigliezza che vale la pena conoscere, perché quasi tutti gli articoli la saltano: alcuni provider usano codici propri per questo. Cloudflare restituisce 524 quando la tua origine accetta una connessione e poi impiega troppo a rispondere, che è la stessa storia raccontata da un altro livello. Se sei dietro una CDN, il numero che ricevi può essere il loro invece di quello standard.

Se sei il visitatore

C’è pochissimo da fare, e questa è la risposta onesta più che una risposta breve.

Aspetta un minuto e ricarica. Un 504 è spesso passeggero - una query lenta, un processo che si sta riavviando, un picco di traffico. Se persiste, controlla se il servizio ha una pagina di stato o se qualcun altro lo sta segnalando, perché il guasto è dalla loro parte e solo loro possono risolverlo.

L’unica cosa davvero utile che puoi fare è dirglielo, con abbastanza dettagli perché riescano a trovarlo. Quale pagina, a che ora e cosa stavi facendo. Un 504 su un pagamento alle 14:32 è qualcosa che un tecnico può andare a cercare in un log; “il vostro sito non funziona” no.

Se il sito è tuo

Quattro cause spiegano la maggior parte dei casi, più o meno in quest’ordine.

  • Una cosa lenta. Una query al database senza indice, un’API esterna che chiami mentre l’utente aspetta, un report cresciuto oltre la dimensione per cui era stato pensato. La richiesta non è bloccata, è solo più lenta della pazienza del proxy.
  • Un timeout impostato sotto la realtà. Nginx usa di default sessanta secondi per una lettura inoltrata. Se la tua richiesta legittima più lenta ne impiega novanta, servirai 504 proprio a chi usa la funzione che conta di più.
  • Worker esauriti. Ogni processo dell’applicazione è occupato, quindi le richieste nuove si accodano dietro e non arrivano nemmeno al codice. Questo arriva a ondate e sembra il sito che cade del tutto, perché di fatto è quello che succede.
  • Il percorso di rete. Un security group, un cambio DNS, un servizio che si è spostato. Meno comune, e di solito totale invece che intermittente.

Scopri quale livello lo ha emesso prima di cambiare qualsiasi cosa. Il log di accesso del proxy registra lo stato che ha restituito e quanto ha aspettato; il log dell’applicazione mostrerà o una richiesta che ci ha messo quel tempo o niente del tutto per quel momento. Questi due casi hanno soluzioni opposte, e tirare a indovinare tra i due è il modo in cui si finisce per alzare un timeout che non era mai stato il problema.

Alzare il timeout è la mossa allettante e da sola è di solito sbagliata. Trasforma un guasto rapido in uno lento e sposta la coda da un’altra parte. È la mossa giusta solo quando sai che il lavoro richiede legittimamente quel tempo e non può essere reso asincrono.

Session Replay

Estensione gratuita per Chrome. Un clic sulla pagina che si comporta male cattura lo screenshot, la console e il registro di rete, e ti restituisce un link da incollare nel ticket.

Installa l'estensione

Perché poi sono così difficili da rincorrere

Un 504 è un istante. Quando qualcuno lo racconta, la query lenta è finita, i worker si sono svuotati, l’ondata è passata, e la pagina si carica perfettamente quando provi.

Così la segnalazione arriva come “prima era rotto” e non c’è niente da guardare. Quello che lo renderebbe rintracciabile è ciò che il browser ha visto in quel momento: quale richiesta è andata in timeout, verso quale host, quanto ha aspettato e cos’altro nella pagina era già fallito. Sta nel pannello di rete finché sta succedendo e sparisce nel momento in cui la scheda viene chiusa.

Questo è l’argomento per catturarlo sul momento invece di descriverlo dopo - un file HAR è il modo consueto di farlo a mano, ed è esattamente quello che porta con sé il registro di rete di una segnalazione. Le stesse prove rispondono all’altra domanda che conviene porsi presto, cioè se il timeout fosse del tuo servizio o di qualcun altro: la colonna dell’host dice quale.

In un paragrafo

Un 504 significa che il server davanti ha chiesto a quello dietro e ha finito la pazienza. È un problema del sito e non tuo, di solito vuol dire lento più che rotto, e si distingue da un 502 per la pausa che lo precede. Se il sito è tuo, scopri quale livello è andato in timeout prima di toccare qualsiasi impostazione di timeout, perché il log che non ha registrato niente e il log che ha registrato novanta secondi ti stanno raccontando due storie diverse.