Codici di stato HTTP

Uno standard con tre decenni di deriva

I codici di stato HTTP hanno attraversato diverse generazioni di specifiche. La RFC 1945 (maggio 1996) standardizzò HTTP/1.0 con le categorie di base 1xx-5xx. La RFC 2616 (giugno 1999) introdusse HTTP/1.1 e fu il riferimento canonico per oltre un decennio. La serie 7230-7235 (giugno 2014) suddivise HTTP/1.1 in più specifiche per argomento. L'attuale standard consolidato è la RFC 9110 «HTTP Semantics» (giugno 2022), che rende obsoleta la suddivisione 7230-7235 ed è la citazione giusta per il lavoro moderno. Il registro completo e aggiornato dei codici assegnati si trova nel registro dei codici di stato HTTP di IANA.

Le cinque categorie in breve

• 1xx Informativo: risposta provvisoria. La richiesta è stata ricevuta e il server continua a elaborarla. Rara nella pratica; utile per gli aggiornamenti di protocollo e per il moderno 103 Early Hints (che consente ai server di precaricare le risorse critiche prima che la risposta completa sia pronta).
• 2xx Successo: la richiesta è stata ricevuta, compresa e accettata. 200 OK è il caso di tutti i giorni; 201 Created per la creazione di risorse; 204 No Content per le azioni riuscite che non hanno nulla da restituire.
• 3xx Reindirizzamento: serve un'ulteriore azione. I reindirizzamenti classici (301 Moved Permanently, 302 Found, 307 Temporary Redirect, 308 Permanent Redirect) più 304 Not Modified per la convalida della cache.
• 4xx Errore del client: il client ha fatto qualcosa di sbagliato: sintassi errata, autenticazione mancante, richiesta di qualcosa che non esiste. La categoria più grande nel traffico del mondo reale.
• 5xx Errore del server: il server ha combinato un guaio. La richiesta era valida; semplicemente il server non è riuscito a soddisfarla. Sono quelli che svegliano di notte gli ingegneri di turno.

I confronti «vs» che mettono in difficoltà tutti

401 contro 403. La coppia in assoluto più confusa. 401 Unauthorized significa «non ti sei autenticato, prova ad accedere» (il nome è tecnicamente fuorviante, riguarda l'autenticazione, non l'autorizzazione). 403 Forbidden significa «sei autenticato, ma non ti è permesso fare questa cosa», le tue credenziali sono valide ma non concedono l'accesso a questa risorsa. Un uso improprio comune: restituire 403 per richieste non autenticate quando la cosa corretta è 401 con un'intestazione WWW-Authenticate.

301 contro 302 contro 307 contro 308. Due assi, permanente contro temporaneo, e comportamento di conservazione del metodo:

Se stai reindirizzando richieste GET a fini SEO, 301 è la scelta convenzionale. Se stai reindirizzando richieste POST o PUT e vuoi che il metodo sia conservato, ti servono 307 o 308.

400 contro 422. 400 Bad Request è per le richieste sintatticamente malformate, JSON non valido, intestazioni obbligatorie mancanti, parametri di query malformati. 422 Unprocessable Entity (originariamente un codice WebDAV, ampiamente adottato dalle API REST) è per le richieste sintatticamente valide con problemi semantici, il JSON si analizza correttamente, ma i valori non superano la convalida di business (quantità negativa su un ordine, e-mail già in uso). Molte API usano entrambi.

502 contro 503 contro 504. Tre diverse modalità di guasto a monte:

• 502 Bad Gateway: il proxy / gateway ha ricevuto una risposta non valida dal server a monte.
• 503 Service Unavailable: il server è sovraccarico o in manutenzione. Spesso abbinato a un'intestazione Retry-After.
• 504 Gateway Timeout: il server a monte non ha risposto in tempo.

404 contro 410. 404 Not Found significa «non sappiamo se questo esista o no.» 410 Gone significa «questo esisteva, è stato rimosso definitivamente.» Impatto SEO: Google tratta 410 come un segnale più forte del fatto che il contenuto sia definitivamente non disponibile e lo rimuove dall'indice più velocemente di quanto faccia per 404.

Convenzioni delle API REST

Le moderne API REST sono convergenti su un insieme abbastanza coerente di convenzioni su cosa significhino i codici di stato per quali azioni:

Implicazioni SEO

• 200 OK: Google indicizza la pagina normalmente.
• 301 Moved Permanently: Google aggiorna l'URL indicizzato a quello nuovo e trasferisce i segnali di posizionamento.
• 302 Found / 307 Temporary Redirect: Google mantiene indicizzato l'URL originale; il posizionamento resta con l'originale.
• 308 Permanent Redirect: Google lo tratta come 301: il posizionamento si trasferisce.
• 304 Not Modified: usato da Googlebot per le richieste condizionali; segnala che il contenuto in cache può essere riutilizzato.
• 404 Not Found: Google rimuove l'URL dal suo indice dopo alcune scansioni.
• 410 Gone: Google rimuove l'URL più velocemente che per 404; il segnale più forte di «scomparso definitivamente».
• 503 Service Unavailable con Retry-After: dice a Googlebot di tornare più tardi. Usalo durante le finestre di manutenzione; evita di usare 503 per errori reali (Google interpreta i 503 prolungati come istruzioni di non scansionare).
• 5xx prolungati: Google riduce la frequenza di scansione e potrebbe alla fine eliminare del tutto l'URL dall'indice.

Codici famosi e culturali

• 418 I'm a teapot: uno scherzo del primo aprile dalla RFC 2324 (Hyper Text Coffee Pot Control Protocol, 1 aprile 1998). Quando l'IETF propose di rimuoverlo dalla specifica nel 2017, la campagna «Save 418» riuscì a mantenerlo in vigore. Alcune API lo usano come marcatore «questo non è reale»; altrimenti innocuo.
• 451 Unavailable For Legal Reasons: RFC 7725 (2015), chiamato così in onore di Fahrenheit 451 di Ray Bradbury. Restituito quando il contenuto è censurato per ordine del tribunale o per richiesta del governo.
• La serie 520-527 di Cloudflare: non standard, usata da Cloudflare per indicare specifici guasti di connessione del server a monte. Comune quando un sito dietro Cloudflare ha problemi.
• Il 444 No Response di Nginx: specifico di Nginx, restituito quando il server chiude la connessione senza inviare alcuna risposta.
• Lo storico 420 Enhance Your Calm di Twitter: un codice di limite di frequenza poi rimosso, usato dalla precedente API di Twitter; sostituito dallo standard 429.

Errori comuni

1. Usare 200 OK per gli errori con un corpo di errore. Restituire {"error": "not found"} con uno stato 200 confonde ogni livello di cache, strumento di monitoraggio e SDK client. Usa il codice di stato giusto.
2. Restituire 403 per richieste non autenticate. Il codice giusto è 401 con un'intestazione WWW-Authenticate.
3. Usare 302 quando intendi 301. Se lo spostamento è permanente, i motori di ricerca hanno bisogno del 301 per trasferire il posizionamento. 302 mantiene indicizzato il vecchio URL.
4. Usare 301 o 302 per i reindirizzamenti POST/PUT. Storicamente questi consentivano ai client di cambiare il metodo in GET. 307 e 308 conservano rigorosamente il metodo originale.
5. Restituire 500 quando si intende 503. Se il server è sovraccarico o in manutenzione, 503 con Retry-After è il segnale corretto, sia per i client sia per Googlebot.
6. Usare 404 per le pagine rimosse definitivamente. 410 Gone è il segnale più forte e viene rimosso più velocemente dagli indici dei motori di ricerca.
7. Dimenticare l'intestazione Location nelle risposte 201 e 3xx. L'intestazione Location è ciò che dice al client dove si trova la nuova risorsa o dove reindirizzare. Senza di essa, i client non possono navigare.

Altre domande frequenti

Quando dovrei restituire 422 invece di 400?

400 Bad Request significa che la richiesta stessa è malformata, JSON non valido, intestazioni obbligatorie mancanti, parametri di query malformati. 422 Unprocessable Entity significa che la richiesta è ben formata ma contiene errori semantici che ne impediscono l'elaborazione, un campo quantità impostato su un numero negativo, un indirizzo e-mail già in uso, una data nel passato per un campo che ammette solo il futuro. Le moderne convenzioni delle API REST sono convergenti su questa distinzione, con la maggior parte delle grandi API (GitHub, Stripe, Twilio) che usa 422 per gli errori di convalida.

Perché Cloudflare a volte restituisce 520, 521, 522…?

I codici 520-527 sono specifici di Cloudflare, segnalano diversi modi in cui il loro edge non è riuscito a raggiungere il tuo server di origine. 520 è il generico «il server web ha restituito un errore sconosciuto»; 521 significa che la tua origine ha rifiutato la connessione; 522 è un timeout di connessione verso la tua origine; 524 significa che la tua origine ha impiegato troppo tempo a rispondere. Non sono nel registro IANA ma si incontrano ampiamente quando i siti dietro Cloudflare hanno problemi di backend.

Il mio browser mi mostrerà quale codice ha restituito la mia API?

Sì, apri i DevTools → scheda Network, fai clic sulla richiesta, e guarda la colonna «Status». I browser mostrano anche pagine generiche per alcuni codici (il gioco del dinosauro nei guasti di connessione di Chrome, le pagine standard 404 / 500); ma il codice numerico effettivo è sempre nella risposta.

Cos'è 103 Early Hints?

Un codice 1xx relativamente nuovo (RFC 8297, 2017) che consente al server di inviare intestazioni Link: rel=preload prima che la risposta completa sia pronta, dicendo al browser di iniziare presto a recuperare le risorse critiche (CSS, font, immagini). Ora supportato da Chrome e distribuito da Cloudflare, Fastly e altre CDN come ottimizzazione delle prestazioni.

Posso inventarmi un mio codice di stato?

Tecnicamente sì (HTTP consente qualsiasi codice di 3 cifre nell'intervallo 100-599. In pratica no) client, proxy e cache trattano i codici sconosciuti in base alla loro prima cifra (quindi 4xx = errore del client in generale, 5xx = errore del server). Alcuni fornitori lo fanno (i 520 di Cloudflare, il 444 di Nginx), ma a meno che tu non controlli entrambe le estremità del collegamento, attieniti al registro IANA. Inventare un 299 non romperà le cose ma non comunicherà nemmeno nulla.

Perché il «codice di stato» si chiama «stato» e non «codice di errore»?

Perché la maggior parte di essi non sono errori. 200 OK è il codice di stato più restituito al mondo, significa «è andato tutto bene.» I codici comunicano lo stato della richiesta: successo, reindirizzamento, errore del client, errore del server. Chiamarli «codici di errore» fa pendere l'attenzione verso i casi negativi che vengono registrati e notati; i codici di successo fanno il loro lavoro silenziosamente a ogni microsecondo.