Codici di errore HTTP, e come capire quale avete davvero davanti

Ogni errore HTTP è una risposta di una riga a una domanda che nessuno ha posto ad alta voce: cosa è successo alla mia richiesta? Il numero è tutta la risposta, ed è deliberatamente scarno, quindi gran parte del lavoro sta nel sapere a quale domanda risponde ciascun numero.

È a questo che serve questa pagina. Non un elenco di tutti i sessanta e passa codici di stato, la maggior parte dei quali non vedrete mai, ma la dozzina abbondante che arriva davvero alle persone, ordinata per quello che vi dice su dove è stato il guasto.

L’unica divisione che conta

La prima cifra è l’unica parte del codice che dovete ricordare.

4xx

Il server vi ha capito e si rifiuta, oppure non è riuscito ad analizzare ciò che è arrivato. Il problema sta nella richiesta

5xx

La richiesta andava bene. Il server non è riuscito a produrre una risposta, o ha scelto di non farlo

Tutto il resto discende da lì. Un 4xx vi manda a guardare ciò che è stato inviato: l’URL, gli header, il corpo, le credenziali. Un 5xx vi manda nei log del server e, se il server non è vostro, potete fare ben poco oltre a segnalarlo bene.

La parola “client” in “errore del client” è il punto in cui le persone si perdono, quindi vale la pena dirlo chiaramente: il client non siete voi. Il client è il software che ha composto la richiesta, e su un sito moderno quello è quasi sempre il JavaScript della pagina stessa. Un 4xx sul sito di qualcun altro di solito è il loro bug con sopra il vostro nome.

I codici 4xx che incontrerete davvero

400 Bad Request è il server che non riesce proprio ad analizzare quello che è arrivato. È l’unico di questa famiglia che riguarda la forma della richiesta invece del permesso o dell’esistenza. Un corpo malformato, un content type mancante, un URL non codificato. Ce n’è una sola versione che potete sistemare voi: un blocco di cookie cresciuto troppo, cosa che una finestra privata conferma in pochi secondi.

401 e 403 sono i due che vengono scambiati di continuo. 401 vuol dire che il server non sa chi siete e vuole delle credenziali. 403 vuol dire che sa esattamente chi siete e la risposta resta no. Mandare credenziali migliori risolve il primo e non risolve mai il secondo.

404 Not Found non ha bisogno di spiegazioni, ma una cosa vale la pena saperla: un 404 su una richiesta che la pagina ha fatto in background, e non nella barra degli indirizzi, di solito significa che una build o un deploy ha perso un file, non che qualcuno ha digitato male.

429 Too Many Requests è l’unico codice di stato che riguarda il vostro comportamento invece del server o della risorsa. È anche l’unico errore in cui riprovare peggiora le cose, perché un nuovo tentativo è un’altra richiesta che il limiter conta.

I codici 5xx, che sembrano identici e significano cose diverse

Tutti e quattro dicono “da parte nostra”, e distinguerli decide dove guarda per primo chiunque.

500 Internal Server Error

L'applicazione è girata e il suo stesso codice ha fallito. Un'eccezione non gestita. Ha risposto, e la risposta era un errore che si è fatta da sola

502 Bad Gateway

Un server davanti ha ricevuto una risposta inutilizzabile dall'applicazione che ha dietro. Il guasto sta fra due server

503 Service Unavailable

Qualcosa ha scelto di non servirvi. Manutenzione, capacità, un rate limiter, o niente di sano verso cui instradare

504 Gateway Timeout

L'applicazione non ha mai risposto in tempo. Il server davanti ha smesso di aspettare

La scorciatoia utile: un 500 è codice che si rompe mentre gira, un 502 è un proxy che non ha ottenuto una buona risposta, un 504 è l’applicazione troppo lenta, e un 503 è l’unico che di solito è voluto. Quest’ultima distinzione conta più di quanto sembri: un 503 spesso porta un header Retry-After che dice esattamente quando tornare, e quasi nessuno lo legge.

Gli errori che non sono affatto codici di stato

Alcuni dei fallimenti più comuni non producono mai un codice di stato, ed è proprio per questo che confondono. La richiesta non è fallita; non si è mai completata.

TypeError: Failed to fetch è l’errore meno informativo di JavaScript. Non c’è nessuno stato da leggere perché la richiesta non è mai arrivata abbastanza lontano da averne uno.

Gli errori CORS sono il browser che si rifiuta di consegnare al vostro codice una risposta che invece è arrivata. Il server ha risposto benissimo; semplicemente non ha detto che la vostra origine era permessa.

ERR_CONNECTION_REFUSED, RESET, CLOSED e TIMED_OUT succedono del tutto sotto HTTP. Ciascuno nomina fin dove è arrivata la connessione prima di morire, che è gran parte di una diagnosi in regalo.

Il contenuto misto è il browser che blocca una risorsa non sicura su una pagina sicura. Non è fallito niente sulla rete; è stata applicata una regola.

Leggerne uno che non è vostro

Se siete visitatori e non la persona che può sistemarlo, tre controlli separano la maggior parte dei casi e richiedono meno di un minuto.

Ricaricate una volta. Parecchi 500 e 503 sono un singolo brutto momento. Se si risolve, non c’è niente da inseguire.

Provate una finestra privata. È il test per la famiglia cookie e header: un 400 che sparisce in privato era un blocco di cookie troppo grande, e uno che non sparisce non è mai stato vostro.

Provate un’altra rete. Un telefono in rete mobile risponde alla domanda che pone un rate limiter. Se l’errore vi segue ovunque è il vostro account o il sito; se sparisce, era l’indirizzo da cui arrivavate. È la stessa domanda del distinguere il vostro bug dal loro disservizio, posta in fretta.

Perché il codice da solo basta di rado a sistemare qualcosa

Ogni errore qui sopra è un riassunto a cui sono state tolte le prove. Non è un caso: un 500 è vago apposta, perché lo stack trace resta sul server, e un 400 non vi dirà quale header lo ha offeso. Il codice nomina la categoria e tace il caso.

Quindi “ho preso un 500” è una segnalazione che a uno sviluppatore non dice quasi nulla e, quando qualcuno va a indagare, la richiesta fallita non c’è più. Quello che ne chiude uno in fretta è la richiesta fallita stessa, il suo orario esatto, e cosa stava facendo la persona.

Il log di rete è dove un codice di stato smette di essere una categoria e diventa un caso: la richiesta che ha preso l’errore, i suoi header e il suo corpo, e il minuto esatto, così chi la prende in carico può confrontarla con un log del server invece di riprodurre prima tutto quanto.

In un paragrafo

La prima cifra è la divisione che conta: un 4xx significa che il problema sta nella richiesta, un 5xx che il server non è riuscito a rispondere, e il “client” incolpato da un 4xx di solito è il JavaScript del sito e non voi. Dentro i 4xx, il 400 riguarda la forma della richiesta, il 401 e il 403 l’identità contro il permesso, e il 429 quanto spesso avete chiesto. Dentro i 5xx, il 500 è codice che si rompe, il 502 un proxy con una risposta cattiva, il 504 niente che risponda in tempo, e il 503 l’unico che di solito è una decisione. Gli errori senza alcun codice di stato, come failed to fetch, CORS, ERR_CONNECTION_* o il contenuto misto, sono quelli che confondono di più, perché la richiesta non si è mai completata invece di fallire. Qualunque sia il vostro, il codice nomina la categoria e tace il caso, quindi catturate la richiesta fallita finché ce l’avete.