Codici di stato HTTP spiegati: quelli che davvero si confondono

La prima cifra è l'unica parte che alcuni client leggono

La RFC 9110 richiede che un client comprenda la classe di un codice di stato anche se non riconosce il codice stesso, e tratti qualsiasi codice ignoto come l'x00 della sua classe. Un client che non ha mai sentito parlare del 451 lo gestisce come un 400; un 599 sconosciuto viene gestito come un 500. È questa regola a rendere lo spazio estensibile, e implica anche che la classe porta quasi tutto il comportamento: le cache decidono da lì se conservare, i proxy se ritentare, i crawler se indicizzare, quasi sempre prima di analizzare qualunque cosa nel tuo corpo di risposta.

La conseguenza pratica è che restituire un 200 con l'errore descritto nel corpo mette il guasto dove nient'altro può vederlo. Il tuo controllo di disponibilità segna verde, il tuo CDN mette in cache la pagina d'errore e un motore di ricerca la indicizza come un documento reale. È il problema del soft 404 nella sua forma generale, e vale un audit, perché la correzione è una riga sul codice di stato e non qualcosa di architetturale.

Redirezioni: quali conservano il tuo POST

La griglia dei quattro codici di redirezione incrocia in realtà due domande: permanente o temporanea, e il metodo sopravvive. 301 e 308 sono permanenti, 302 e 307 temporanei; 307 e 308 sono i due che vietano al client di modificare la richiesta. MDN è netta sul perché esista la coppia più recente: il 301 richiedeva già che metodo e corpo restassero invariati, ma quel requisito era gestito male dai client vecchi, che passavano a GET. Nessuno poteva sistemare il parco installato, così sono stati coniati due codici nuovi con la garanzia scritta nella definizione.

La scelta discende quindi dal traffico. Per una pagina che riceve solo GET, il 301 va bene ed è ciò a cui i motori di ricerca sono più abituati. Per un percorso API, il bersaglio di un form o qualsiasi cosa possa ricevere POST, PUT o DELETE, usa 308 e la richiesta arriva intatta. Un avvertimento sulla permanenza: i browser mettono in cache un 301 in modo aggressivo e alcuni lo tengono molto più a lungo di quanto ti aspetti, così un 301 emesso durante un esperimento può sopravvivergli su macchine a cui non hai accesso. Servi 302 o 307 finché stai ancora decidendo.

Gli errori restituiti sbagliati più spesso

401 e 403 sono la coppia che costa più tempo di assistenza. Il 401 significa che la richiesta era priva di credenziali di autenticazione valide, e MDN nota che viene inviato con un header WWW-Authenticate che descrive lo schema atteso dal server: è un invito a riprovare con le credenziali. Il 403 è la situazione opposta: le credenziali sono perfettamente valide e il client non ha comunque il permesso per questa azione. Restituire un 401 a un utente autenticato dice al suo client di riautenticarsi, il che produrrà esattamente lo stesso rifiuto, e gli fa credere che l'accesso sia rotto quando non lo è.

404 e 410 differiscono solo nel grado di certezza, ed è proprio questo il punto. L'indicazione di MDN è esplicita: se chi gestisce il server non sa se la condizione è temporanea o permanente, deve usare 404. Il 410 si usa quando hai rimosso la cosa di proposito e non tornerà: è cacheabile per impostazione predefinita e dice ai crawler di smettere di chiedere. Retry-After, invece, è un header che porta un ritardo in secondi o una data HTTP; su un 503 stima quanto il servizio resterà non disponibile e su un 429 dice quanto attendere prima di una nuova richiesta. È un'indicazione, non un contratto, e MDN nota che il supporto nei client è disomogeneo — ma Googlebot lo rispetta, il che basta a giustificarne l'uso durante una manutenzione pianificata.

Domande frequenti

Una migrazione di sito deve usare 301 o 308?

Per pagine richieste solo con GET, il 301 è il valore sicuro e quello che ogni crawler e proxy gestisce da decenni. Ricorri al 308 per tutto ciò che può ricevere POST, PUT o DELETE — endpoint di form, rotte API, ricevitori di webhook — perché è lì che un client che declassa il metodo in silenzio trasforma una redirezione in un corpo di richiesta perduto. Nulla vieta di usarli entrambi nella stessa migrazione, rotta per rotta.

Cosa deve restituire un'API quando la validazione fallisce?

Usa 400 Bad Request quando la richiesta stessa è malformata e il server non riesce ad analizzarla: JSON rotto, un header obbligatorio mancante. Usa 422 Unprocessable Content quando la sintassi è corretta ma il contenuto viola le tue regole, come un corpo ben formato con una data di fine precedente a quella di inizio. Ciò che non devi restituire è un 500, che addossa al server un errore del client e inquina il tuo budget di errore, né un 200 con il problema descritto nel corpo, che nasconde il guasto a ogni strato tra te e il chiamante.

I 404 danneggiano il posizionamento?

Un 404 è una risposta valida e onesta, e una parte normale di qualsiasi sito che esista da un po'; una pagina che non c'è più deve dirlo. Il danno viene dai sostituti. Un soft 404 — una pagina gentile servita con stato 200 — tiene URL morti nell'indice e spende budget di scansione per nulla. Reindirizzare in blocco ogni pagina mancante alla homepage è lo stesso errore travestito da 301. Se la rimozione è stata deliberata e permanente, il 410 lo dice con chiarezza.