Cosa significano i 502 Bad Gateway e di chi è la colpa

Un 502 Bad Gateway è un server che ti dice che un altro server, quello su cui si affidava, ha risposto con qualcosa che non poteva usare. Non è “il sito è down” esattamente, e non è nemmeno “hai fatto qualcosa di sbagliato”: una macchina nel mezzo ha chiesto alla macchina dietro di lei la tua pagina, e quello che è tornato indietro era spazzatura, una porta sbattuta, o nulla che avesse senso.

La parola gateway è l’indizio. Il server che hai raggiunto non è quello che crea la tua pagina; è una facciata, un reverse proxy o un load balancer, che sta davanti all’applicazione che fa il vero lavoro. Quando quella facciata riceve una risposta rotta da dietro, l’unica cosa onesta che può fare è riferire che la risposta era cattiva. Che è esattamente quello che significa 502.

L’architettura a due server

Quasi ogni sito di una certa dimensione è composto da almeno due macchine. C’è quella a cui il tuo browser si connette per primo - nginx, un CDN edge, un load balancer cloud - e dietro di essa il server applicativo che effettivamente esegue il codice e crea la pagina.

La facciata prende la tua richiesta e la passa dietro. La maggior parte delle volte l’applicazione risponde correttamente e la facciata ti passa quella risposta, invisibilmente. Un 502 è quello che vedi quando quel secondo passaggio fallisce: la facciata ha chiesto, e la risposta che ha ricevuto non era una risposta HTTP valida che potesse inoltrare.

Quindi un 502 non riguarda mai davvero il server che hai raggiunto. È un messaggio su quello che non hai raggiunto.

502 rispetto a 504, che vengono costantemente confusi

Provengono dallo stesso posto - il server davanti, che riferisce su quello dietro - e distinguerli riduce notevolmente la causa.

502 Bad Gateway

L'upstream ha risposto, e la risposta era inutilizzabile - una connessione rifiutata, un processo bloccato, spazzatura sul filo. Solitamente veloce

504 Gateway Timeout

L'upstream non ha risposto affatto nel tempo consentito. Solitamente lento, e la pausa prima dell'errore è essa stessa l'indizio

In breve: 502 è “ha detto qualcosa di sbagliato”, 504 è “non ha detto ancora nulla”. Un 502 arriva velocemente e punta a qualcosa di rotto, bloccato o che rifiuta connessioni; un 504 arriva lentamente e punta a qualcosa di bloccato o sovraccarico. Se l’errore è tornato quasi istantaneamente, è molto più probabile un 502 che un 504, indipendentemente da quello che dice la pagina.

Una cosa sfumata che la maggior parte degli articoli tralascia: i provider rinominano questo. Cloudflare restituisce 502 proprio quando la tua origin invia una risposta non valida, e il suo proprio 520 per una risposta così malformata che non si adatta a nessun codice standard. Dietro un CDN, il numero che vedi potrebbe essere il resoconto del CDN dello stesso evento piuttosto che del tuo server.

Se sei il visitatore

Ricarica una volta, perché un 502 è spesso un singolo worker bloccato o un processo bloccato a metà del riavvio, e la richiesta successiva atterra su uno sano. Se si risolve, non c’è nulla da inseguire.

Se persiste, la colpa è dal lato del sito e non c’è genuinamente molto che tu possa fare al di là di dirgli, perché nessuna impostazione nel tuo browser raggiunge un processo rotto sul loro server. Prima di presumere che sia colpa tua, conferma che non sia locale: il controllo più veloce è puntare il controllo dello stato HTTP all’indirizzo, che richiede la pagina dal nostro server piuttosto che dal tuo e riporta il codice che è tornato indietro. Se vede anche il 502, il problema non è la tua connessione.

Se è il tuo sito

Un 502 dice che la facciata non poteva usare quello che l’applicazione ha inviato, quindi la domanda è cosa ha fatto l’applicazione. Ci sono solo poche risposte comuni.

Il processo applicativo è down o sta bloccandosi. La causa più frequente di gran lunga. La facciata prova a connettersi e riceve “connessione rifiutata” perché nulla è in ascolto, o il processo accetta la richiesta e muore a metà della risposta. Verifica se l’app è effettivamente in esecuzione, e leggi i suoi log per un blocco o un kill per mancanza di memoria nel momento dell’errore - i log della facciata diranno solo che l’upstream ha fallito, mai il motivo.

Una mancata corrispondenza di timeout tra gli strati. Se l’applicazione impiega più tempo a rispondere di quanto la facciata sia disposta ad aspettare, alcuni proxy lo segnalano come 502 piuttosto che 504, chiudendo la connessione e definendo la risposta mezza finita come cattiva. Quando un 502 si correla con richieste lente piuttosto che blocchi, guarda qui.

Un deploy difettoso. Una nuova build che non riesce ad avviarsi, ascolta sulla porta sbagliata, o risponde con header che la facciata rifiuta, trasformerà ogni richiesta in un 502 nel momento in cui diventa live. Se gli errori sono iniziati con un deploy, quello è il primo posto da guardare, e un rollback è più veloce di una diagnosi.

Qualcosa tra gli strati. Un proxy_pass mal configurato, un nome hostname upstream che non si risolve più, un security group che ha silenziosamente smesso di consentire alla facciata di raggiungere l’app - la connessione non si completa mai e la facciata segnala un bad gateway. Questi sono i più lenti da trovare perché nulla è bloccato; un collegamento nella catena semplicemente ha smesso di trasportare traffico.

Il motivo per cui questi errori sono difficili da rintracciare in seguito

Un 502 è spesso scomparso nel momento in cui qualcuno guarda. Il worker bloccato si riavvia, il deploy viene ripristinato, il picco di traffico passa, e il log della facciata dice solo che una richiesta upstream ha fallito alle 09:14 - non quello che ha detto l’upstream, non quale processo, non il motivo.

Quello che lo risolve è la prova catturata mentre sta accadendo: la richiesta che ha fallito, lo status esatto, il timing, e cosa stava facendo la persona quando è apparso. Un 502 che un utente segnala un’ora dopo, da memoria, è una supposizione. Un 502 con la richiesta fallita e il suo timestamp allegato è una riga che puoi abbinare al log dell’applicazione e alla storia del deploy e chiudere.

Il log di rete contiene la richiesta fallita con il suo 502 e il momento in cui è accaduto, salvato mentre stava andando male piuttosto che ricordato in seguito - che è la differenza tra un report su cui qualcuno può agire e uno che deve prima riprodurre.

In un paragrafo

Un 502 Bad Gateway è un server di prima linea che dice che il server dietro di esso ha fornito una risposta che non poteva usare - bloccato, rifiutato, o malformato - e arriva velocemente, che è quello che lo distingue dal lento 504. Se stai visitando, ricarica una volta e poi assumi che sia dal loro lato. Se è il tuo, verifica se l’applicazione è in esecuzione e cosa ha registrato, sospetta l’ultimo deploy se il timing corrisponde, e cattura la richiesta fallita mentre ce l’hai, perché un 502 è quasi impossibile da rintracciare una volta che è passato.