Cosa significano i codici di stato HTTP

Ogni volta che il tuo browser carica una pagina o un'app chiama un'API, il server risponde con un codice di stato a tre cifre. Il più delle volte non lo vedi mai, ma quando qualcosa si rompe — un 404, un 500 — quel numero è il primo indizio. Questa guida ti insegna a leggere i codici di stato a colpo d'occhio.

Leggi la prima cifra

Il trucco è che la prima cifra ti dice la categoria, così puoi capire l'intento di un codice mai visto:

• 1xx — Informational: ricevuto, ancora in elaborazione (raro nell'uso quotidiano).
• 2xx — Success: ha funzionato.
• 3xx — Redirection: la risorsa è altrove.
• 4xx — Client error: la richiesta era sbagliata (lato tuo).
• 5xx — Server error: la richiesta andava bene, il server ha fallito.

Quella divisione 4xx contro 5xx è la distinzione più utile nel debug: 4xx significa correggi la richiesta; 5xx significa che la colpa è del server.

I codici che incontrerai davvero

Successo e reindirizzamenti

• 200 OK — la risposta standard «ha funzionato».
• 201 Created — una nuova risorsa è stata creata (dopo un POST).
• 301 Moved Permanently — questo URL si è spostato in modo permanente; aggiorna i tuoi link. Importante per la SEO.
• 302 Found — un reindirizzamento temporaneo; continua a usare l'URL originale.
• 304 Not Modified — la tua copia in cache è ancora valida, quindi non è stato rinviato nulla.

Errori del client (4xx)

• 400 Bad Request — la richiesta era malformata.
• 401 Unauthorized — devi autenticarti (accedere).
• 403 Forbidden — sei autenticato ma non autorizzato.
• 404 Not Found — la risorsa non esiste.
• 429 Too Many Requests — sei soggetto a rate limit; rallenta.

Errori del server (5xx)

• 500 Internal Server Error — un guasto generico lato server.
• 502 Bad Gateway — un server a monte ha restituito una risposta errata.
• 503 Service Unavailable — il server è sovraccarico o offline per manutenzione.
• 504 Gateway Timeout — un server a monte non ha risposto in tempo.

401 vs. 403: una confusione comune

Questi due sembrano simili ma differiscono di una parola. 401 Unauthorized in realtà significa «non autenticato» — il server non sa chi sei, quindi accedi. 403 Forbidden significa che il server sa chi sei e non sei comunque autorizzato. Uno riguarda l'identità, l'altro il permesso.

L'elenco completo

Per ogni codice registrato con il suo significato — ricercabile e raggruppato per classe — vedi il nostro riferimento completo dei codici di stato HTTP. Se stai facendo il debug delle risposte API, le nostre guide su JWT e codifica URL trattano altre due cose in cui ti imbatterai di continuo.