Codici di stato HTTP
I codici più frequenti in API e CDN. Quelli sperimentali rari sono esclusi.
| Codice | Nome | Significato |
|---|---|---|
| 200 | OK | Successo con corpo |
| 201 | Creato | Risorsa creata |
| 204 | Nessun contenuto | Successo, corpo vuoto |
| 301 | Spostato permanentemente | Reindirizzamento permanente |
| 302 | Trovato | Reindirizzamento temporaneo |
| 304 | Non modificato | Usa la copia in cache |
| 400 | Richiesta non valida | Richiesta del client non valida |
| 401 | Non autorizzato | Autenticazione richiesta o fallita |
| 403 | Vietato | Autenticato ma negato |
| 404 | Non trovato | La risorsa non esiste |
| 405 | Metodo non consentito | Metodo HTTP errato |
| 408 | Timeout della richiesta | Client troppo lento |
| 409 | Conflitto | Conflitto di stato |
| 410 | Non più disponibile | Rimosso definitivamente |
| 422 | Entità non elaborabile | Semantica non valida |
| 429 | Troppe richieste | Limitato di frequenza |
| 500 | Errore interno del server | Guasto del server |
| 502 | Gateway non valido | Risposta upstream non valida |
| 503 | Servizio non disponibile | Sovraccarico o non disponibile |
| 504 | Timeout del gateway | Timeout upstream |
Note
- 401 vs 403: credenziali assenti/fallite contro autenticato ma non autorizzato.
- Il CDN può rispondere 5xx se l’origine non è raggiungibile.
Le cinque classi di codici di stato
La prima cifra indica chi è responsabile e approssimativamente cosa è accaduto. Le risposte 1xx sono informative e raramente visibili dal client. Le 2xx indicano successo: 200 OK con un corpo, 204 No Content senza corpo, 206 per un download parziale. Le 3xx segnalano che la risorsa si trova altrove. Le 4xx indicano che la richiesta è errata: sintassi sbagliata, credenziali mancanti o superamento di un limite di velocità. Le 5xx significano che il server ha fallito nonostante la richiesta fosse corretta. Leggere solo la prima cifra già suggerisce se correggere il client o risolvere il problema sul lato server.
Scegliere il redirect giusto
301 e 308 indicano entrambi una permanente; 302 e 307 indicano entrambi una temporanea. La differenza sta nel trattamento del metodo: 301 e 302 storicamente consentivano ai client di convertire una POST in GET, mentre 307 e 308 preservano il metodo e il corpo originali, aspetto rilevante per le API e l'invio di form. Usa 301 quando un URL è davvero cambiato in modo definitivo, e 302 o 307 per reindirizzamenti temporanei come pagine di manutenzione o test A/B. Attenzione alle catene: ogni hop aggiuntivo introduce latenza e perdita di valore dei link, quindi reindirizza direttamente alla destinazione finale.
Gestire gli errori 4xx
401 indica che l'autenticazione manca o non è andata a buon fine, quindi inviare credenziali valide può risolvere il problema; 403 significa che la richiesta è stata compresa e autenticata ma non è consentita, e riprovare con le stesse credenziali non serve. 404 indica che la risorsa non esiste; 410 segnala che esisteva ed è stata deliberatamente rimossa. 429 indica che è stato superato un limite di frequenza e si dovrebbe ridurre la pressione, rispettando eventualmente l'intestazione Retry-After. 400 indica solitamente input non valido, 405 che il metodo non è corretto per quell'URL, e 422 che la sintassi era valida ma il contenuto non ha superato la convalida.
Leggere i codici 5xx
500 è un errore interno generico; 502 Bad Gateway indica che un server a monte ha restituito qualcosa di irricevibile; 503 indica che il servizio è temporaneamente non disponibile o sovraccarico; 504 segnala un timeout di un server a monte. Sono problemi del server, non del chiamante, quindi la soluzione consiste nel ripetere la richiesta con attesa esponenziale, verificare lo stato dei server a monte o ridurre il carico. Una CDN può emettere 502, 503 o 504 per conto di un origin che non riesce a raggiungere, motivo per cui lo stesso errore può provenire da fonti molto diverse: controlla le intestazioni server e cache-status per capire la causa.
Codici di stato nella pratica: API e cache
Due usi comuni meritano attenzione. Innanzitutto la cache: una risposta 200 con intestazione Cache-Control può essere memorizzata, 304 Not Modified dice al client di riutilizzare la copia locale, e una 5xx non deve essere memorizzata. In secondo luogo le API: una POST che crea una risorsa dovrebbe restituire 201 con intestazione Location, una DELETE spesso restituisce 204, e una PATCH che non modifica nulla può restituire 200 o 204. I client ben progettati gestiscono prima per classe (2xx, 4xx, 5xx) e solo in seguito valutano il codice esatto, mantenendo semplice e prevedibile la logica di ritentativi e attesa.
Domande frequenti
- Cosa significa il codice HTTP 403?
- 403 Forbidden significa che il server ha compreso e autenticato la richiesta ma nega l’accesso alla risorsa. A differenza del 401, rifare il login non risolve.
- Qual è la differenza tra i redirect HTTP 301 e 302?
- 301 indica uno spostamento permanente: client e motori di ricerca devono usare il nuovo URL. 302 è un redirect temporaneo e l’URL originale resta valido.
- Cosa significa HTTP 429 e come si risolve?
- 429 significa che è stato raggiunto un limite di richieste. Rallenta e rispetta l’header Retry-After se il server lo invia.