I codici di stato HTTP sono i numeri di tre cifre che un server restituisce in cima a ogni risposta per riassumere cosa è successo. Sono il modo in cui browser, client, proxy e CDN decidono se mettere in cache, reindirizzare, riprovare o mostrare un errore all'utente.
Ogni codice di stato rientra in una di cinque classi in base alla prima cifra: 1xx informativi, 2xx successo, 3xx reindirizzamento, 4xx errore del client, 5xx errore del server. Una volta nota la classe, di solito conosci il significato generale ancora prima di cercare il codice specifico.
La maggior parte delle app usa solo un piccolo nucleo (200, 201, 204, 301, 302, 304, 400, 401, 403, 404, 409, 422, 429, 500, 502, 503). Sapere cosa *significa* ciascuno, e la differenza tra 401 Unauthorized e 403 Forbidden, o tra 301 Moved Permanently e 302 Found, è ciò che ti rende uno sviluppatore backend o di API più solido.
Cosa imparerai usando questo elenco
La prima cifra indica sempre la classe: 1xx informativi, 2xx successo, 3xx reindirizzamento, 4xx errore del client, 5xx errore del server.
I codici di stato sono *parte del contratto* che un'API offre: i client dovrebbero decidere in base a quelli, non estrarre i messaggi di errore dal body.
4xx significa che il client ha sbagliato qualcosa (input non valido, autenticazione mancante, risorsa inesistente). 5xx significa che il server ha fallito, qualunque cosa abbia fatto il client.
Alcuni codici hanno sfumature: 401 vs 403, 301 vs 308, 200 vs 204. Le differenze contano per la cache e per i nuovi tentativi.
Come usare l'elenco dei codici di stato passo dopo passo
1
Cerca per codice o nome
Scrivi un numero (404, 429) o una parola chiave (auth, redirect, rate limit) e i codici corrispondenti si filtrano in tempo reale.
2
Filtra per classe
Usa i pulsanti delle classi (1xx, 2xx, 3xx, 4xx, 5xx) per restringere l'elenco quando stai esplorando invece di cercare.
3
Leggi la spiegazione in parole semplici
Ogni voce spiega quando viene inviato il codice, come si comporta di solito il client e la causa più comune.
4
Confronta i codici correlati
Usa i collegamenti tra le coppie che si confondono (401 vs 403, 301 vs 302) per scegliere quello giusto per la tua API.
Successo, ma senza body. Comune dopo chiamate DELETE o PUT che non devono restituire dati.
Sono tutti e tre codici di successo: la differenza è cosa contiene la risposta. 201 dovrebbe includere un header Location che punta alla nuova risorsa; 204 è vuoto per definizione.
Reindirizzamento temporaneo. I browser ricontrollano l'URL originale a ogni richiesta; i segnalibri restano sul vecchio URL.
Usa 301 quando hai davvero spostato una risorsa (rebranding, ristrutturazione degli URL). Usa 302 per reindirizzamenti di breve durata come test A/B, redirect di login o pagine di manutenzione.
Il server sa chi sei, ma non hai il permesso per questa risorsa.
Se inviare credenziali diverse potrebbe risolvere, restituisci 401. Se nessuna credenziale aiuterebbe (la risorsa è semplicemente vietata a questo utente), restituisci 403.
Gateway timeout: un proxy ha raggiunto il server a monte ma non ha ricevuto risposta in tempo.
Sono tutti e quattro errori del server, ma raccontano storie molto diverse a chi fa debug. 500 è la tua app; 502 e 504 indicano il percorso di rete; 503 indica la capacità.
Errori comuni con i codici di stato HTTP
Restituire 200 OK con {"error": "..."} nel body. I codici di stato fanno parte del contratto: usa quello giusto (400, 404, 500) così i client possono decidere in base a quello.
Usare 401 per gli errori di permesso. 401 è per l'autenticazione; i permessi negati sono 403.
Usare 200 per le risorse appena create invece di 201 con un header Location.
Restituire 404 per gli accessi non autorizzati. Nasconde la risorsa a chi fa tentativi, ma confonde anche i client che hanno un accesso legittimo. Di solito 403 è più chiaro.
Confondere 429 Too Many Requests con 503 Service Unavailable. Usa 429 per i limiti di frequenza per client, 503 per il sovraccarico globale.
Domande frequenti sui codici di stato HTTP
Cosa significa l'errore HTTP 404?
404 Not Found significa che il server ha capito la richiesta ma la risorsa a quell'URL non esiste. Nella maggior parte dei casi il percorso è sbagliato, la risorsa è stata eliminata o l'URL è stato digitato male.
Che differenza c'è tra 401 e 403?
401 Unauthorized significa che non sei autenticato: il server non sa chi sei. 403 Forbidden significa che sei autenticato ma non hai il permesso per la risorsa. Inviare credenziali diverse potrebbe risolvere un 401; non risolverà un 403.
Che differenza c'è tra 301 e 302?
301 Moved Permanently è un reindirizzamento permanente: browser e motori di ricerca aggiornano i loro dati. 302 Found è un reindirizzamento temporaneo: i client continuano a visitare l'URL originale. Usa 301 per gli spostamenti permanenti, 302 per le deviazioni temporanee.
Cosa significa l'errore HTTP 500?
500 Internal Server Error è un errore generico lato server, di solito lanciato quando un'eccezione non gestita risale fino in cima. Il client non ha fatto nulla di sbagliato: è il tuo server che non è riuscito a elaborare una richiesta valida.
Devo usare sempre un codice di stato specifico?
Sì. Un 200 OK generico per gli errori o 500 per qualsiasi problema rende le API più difficili da usare. Scegli il codice più specifico adatto al caso: client, proxy, sistemi di monitoraggio e logiche di retry decidono tutti in base al codice di stato.
Cosa significa HTTP 429?
429 Too Many Requests viene inviato quando un client ha raggiunto un limite di frequenza. La risposta dovrebbe includere un header Retry-After che dice al client quando può riprovare senza problemi.
Cosa significa HTTP 403 Forbidden?
403 Forbidden significa che il server ha capito la richiesta e sa chi sei, ma si rifiuta di farti accedere alla risorsa. A differenza di 401, autenticarti di nuovo non serve: il tuo account semplicemente non ha il permesso. Le cause comuni sono ruoli o scope mancanti, liste di IP consentiti o una risorsa privata di un altro utente.
Cosa significa HTTP 502 Bad Gateway?
502 Bad Gateway significa che un server che fa da proxy o gateway (una CDN, un load balancer o un reverse proxy) ha ricevuto una risposta non valida o vuota dal server a monte a cui ha inoltrato la tua richiesta. Di solito indica che il backend è giù, va in crash o è configurato male, non che la tua richiesta sia sbagliata.
Quanti codici di stato HTTP esistono?
Ci sono cinque classi (1xx-5xx) e circa 60 codici standard registrati presso IANA, anche se la maggior parte si usa raramente. In pratica lo sviluppo web e di API di tutti i giorni si basa su circa 15-20 codici principali: 200, 201, 204, 301, 302, 304, 400, 401, 403, 404, 409, 422, 429, 500, 502 e 503. L'elenco con ricerca qui sopra include ogni codice standard con una descrizione in parole semplici.
