Riferimento codici di stato HTTP

Il Riferimento Codici di Stato HTTP è un indice completo e ricercabile di ogni codice di stato definito nelle specifiche HTTP — da 100 Continue fino a 511 Network Authentication Required. Ogni voce mostra il nome canonico, la RFC che lo definisce, cosa il codice significa effettivamente, quando inviarlo, quando non inviarlo e gli errori comuni che colpiscono i veri database di codice. Un filtro in tempo reale e i chip delle categorie ti consentono di passare da una classe all'altra con un solo clic.

A differenza di un semplice foglio di riferimento, questo strumento offre a ciascun codice la propria micro-pagina con tre pannelli codificati a colori (cosa fare / cosa evitare / errori comuni) e gestori pronti da incollare per Express.js, Django, FastAPI e Go net/http. Il diagramma lineare animato mostra il percorso della richiesta da client a server e il flusso del codice di stato scelto che ritorna — utile per i nuovi arrivati che stanno imparando cosa rappresenta realmente un codice di stato sulla rete.

Perché è importante un riferimento ai codici di stato

Come utilizzare il Riferimento Codici di Stato HTTP

1. Ricerca rapida. Digita un codice (404) o un frammento di nome (teapot, gateway) nella casella di ricerca in alto e invia. La voce corrispondente si aprirà con il pannello dei dettagli completo.
2. Sfoglia per classe. Clicca su uno qualsiasi dei 5 chip (1xx, 2xx, 3xx, 4xx, 5xx) per filtrare la griglia in base a quella classe. Clicca su Tutti per ripristinare.
3. Filtro in tempo reale. La casella di filtro appena sopra la griglia restringe le schede mentre digiti — utile quando ricordi solo metà di un nome come too many o precondition.
4. Ispeziona un codice. Clicca su qualsiasi scheda per aprire il suo pannello dei dettagli. Vedrai il significato, quando usarlo, quando non usarlo, gli errori comuni e un blocco di snippet per 4 framework.
5. Copia uno snippet. Utilizza il selettore di schede e il piccolo pulsante Copia per prelevare un gestore pronto da incollare.
6. Confronta i codici adiacenti. Il pannello dei dettagli termina con le schede sorelle della stessa classe (1xx / 2xx / 3xx / 4xx / 5xx) per un rapido confronto affiancato.

Le classifica delle cinque classi di stato HTTP in sintesi

Coppie frequentemente confuse

• 401 vs 403. 401 significa non autenticato — alla richiesta mancano credenziali valide. 403 significa autenticato ma non autorizzato — le credenziali sono corrette ma l'utente non dispone dei permessi necessari.
• 404 vs 410. 404 significa sconosciuto: forse esiste altrove, o forse si tratta di un errore di battitura. 410 significa rimosso deliberatamente: i motori di ricerca dovrebbero rimuoverlo dall'indice.
• 301 vs 302 vs 307 vs 308. 301 / 308 sono permanenti (308 conserva rigorosamente il metodo e il corpo), 302 / 307 sono temporanei (307 conserva rigorosamente il metodo e il corpo). Utilizza 307 / 308 per i reindirizzamenti di POST / PUT / PATCH.
• 400 vs 422. 400 significa che il corpo della richiesta è malformato (JSON non valido, campo mancante). 422 significa che l'analisi del corpo è andata a buon fine ma i valori violano le regole aziendali (formato email non valido, quantità fuori intervallo).
• 502 vs 503 vs 504. 502 significa che il server a monte ha inviato dati non validi. 503 significa che il server è sovraccarico o in manutenzione. 504 significa che il server a monte non ha risposto in tempo.
• 409 vs 412. 409 indica un conflitto con lo stato corrente della risorsa. 412 significa nello specifico che un header di precondizione (If-Match, If-Unmodified-Since) è risultato falso.

Header da associare a codici di stato specifici

• 201 Created — dovrebbe includere l'header Location che punta alla nuova risorsa.
• 301 / 302 / 307 / 308 — deve includere l'header Location con l'URL di destinazione.
• 304 Not Modified — deve replicare gli header che sarebbero apparsi in un codice 200 (ETag, Cache-Control, Vary).
• 401 Unauthorized — deve includere l'header WWW-Authenticate elencando gli schemi accettati (Basic, Bearer).
• 405 Method Not Allowed — deve includere l'header Allow elencando i metodi che sono consentiti.
• 413 / 429 / 503 — spesso includono l'header Retry-After (secondi o data-HTTP) in modo che i client eseguano il back-off correttamente.
• 416 Range Not Satisfiable — deve includere l'header Content-Range: bytes */<length>.

Codici di stato che puoi quasi sempre ignorare

Una manciata di codici sono tecnicamente validi ma estremamente rari nelle API moderne: 305 Use Proxy (deprecato), 306 (riservato, inutilizzato), 305, 506 Variant Also Negotiates, 510 Not Extended e 508 Loop Detected. La maggior parte viene conservata nel registro per motivi storici. Se la tua libreria o il tuo middleware ne emette uno, trattalo come una segnalazione di bug nei confronti della libreria — non come un indizio per gestirlo in modo speciale.

FAQ

Lo strumento include codici provenienti da RFC diverse dalla 9110?

Sì. Copre la RFC 9110 (semantica HTTP), la RFC 6585 (4xx / 5xx aggiuntivi), la RFC 4918 (WebDAV), la RFC 5842 (associazioni WebDAV), la RFC 7725 (451), la RFC 8297 (103 Early Hints), la RFC 8470 (425 Too Early) e la celebre e scherzosa RFC 2324 (418 Teapot).

Questi codici sono validi in HTTP/2 e HTTP/3?

Sì. La semantica dei codici di stato è definita nella RFC 9110, che è il documento sulla semantica HTTP indipendente dalla versione. HTTP/2 (RFC 9113) and HTTP/3 (RFC 9114) modificano solo il framing e il trasporto.

Posso collegarmi direttamente a un codice specifico?

Invia il modulo con un singolo codice (ad esempio 404) e il pannello dei dettagli si caricherà sotto il modulo. L'URL mostra la tua ricerca ed è sicuro da condividere — aprendolo verrà caricato lo stesso risultato.

Perché il mio framework non mi consente di restituire il codice 418?

Le versioni precedenti di alcune librerie HTTP si rifiutano di emettere codici che non sono presenti nel loro registro interno. La soluzione consiste nell'aggiornare la libreria o, ove possibile, scrivere manualmente la riga di stato.

Un'API dovrebbe mai restituire un codice 200 con un corpo di errore?

No. Il monitoraggio, i tentativi e gli intermediari presuppongono tutti che la classe 2xx indichi il successo. Se devi restituire una struttura di errore, restituisci un codice 4xx o 5xx appropriato e inserisci i dettagli strutturati all'interno del corpo. Il formato Problem Details for HTTP APIs (RFC 9457) è un ottimo modello.

Esiste un registro autorevole dei codici di stato HTTP?

Sì. Lo IANA mantiene il registro all'indirizzo iana.org/assignments/http-status-codes. Questo strumento rimane in sincrono con tale registro oltre alle RFC più comunemente citate.