Adamant Solutions

Codici di stato HTTP per chi progetta API

Cosa significa ogni codice e l’errore che i team commettono più spesso. Le definizioni seguono la RFC 9110 e le RFC collegate. Cerca per numero o per parola (per esempio 429 o rate limit). I nomi dei codici restano quelli ufficiali in inglese. Contiamo solo le visite anonime (niente cookie, niente IP).

100 Continue

Il server ha ricevuto gli header della richiesta; il client può inviare il body (usato con Expect: 100-continue).

Errore comune: Raramente si gestisce a mano: se ne occupano le librerie HTTP. Non restituirlo dal codice applicativo.

101 Switching Protocols

Il server accetta di cambiare protocollo, per esempio verso WebSocket dopo una richiesta Upgrade.

Errore comune: Non è una risposta alle normali chiamate API.

200 OK

La richiesta è riuscita e la risposta ha un body (risultato di una GET, aggiornamento che restituisce la risorsa).

Errore comune: Restituire 200 con un messaggio di errore nel body nasconde i fallimenti a client, cache e monitoraggio.

201 Created

È stata creata una nuova risorsa. Invia un header Location con il suo URL e, di solito, la risorsa nel body.

Errore comune: Usare 200 per una creazione, oppure omettere Location.

202 Accepted

La richiesta è stata accettata per un’elaborazione non ancora conclusa (lavoro asincrono). Fornisci un URL di stato o un id del job.

Errore comune: Restituire 202 senza offrire alcun modo per conoscere l’esito.

204 No Content

Successo senza body: tipico per DELETE e per PUT/PATCH che non restituiscono nulla.

Errore comune: Inviare un body con 204 (deve essere vuoto).

206 Partial Content

Una richiesta di intervallo è riuscita (header Range): usata per download ripristinabili e contenuti multimediali.

Errore comune: Ignorare Range e inviare sempre il file intero.

301 Moved Permanently

La risorsa ha un nuovo URL permanente. Client e motori di ricerca dovrebbero aggiornare i link.

Errore comune: Usarlo per spostamenti temporanei: i browser lo mettono in cache. Una POST può diventare GET; usa 308 per mantenere il metodo.

302 Found

Redirect temporaneo (storicamente ambiguo sul metodo).

Errore comune: Preferisci 303 o 307 per essere espliciti sul metodo.

303 See Other

Dopo una POST, reindirizza il client a una GET su un’altra risorsa (per esempio il risultato).

Errore comune: Usare 302 e affidarsi al comportamento del singolo client.

304 Not Modified

GET condizionale (If-None-Match / If-Modified-Since): la copia in cache è ancora valida; nessun body.

Errore comune: Inviare 200 con il body completo quando l’ETag corrisponde, sprecando banda.

307 Temporary Redirect

Redirect temporaneo che mantiene metodo e body (una POST resta una POST).

Errore comune: Confonderlo con 302.

308 Permanent Redirect

Redirect permanente che mantiene metodo e body.

Errore comune: Usare 301 in API dove una POST deve restare POST.

400 Bad Request

La richiesta è malformata o non supera la validazione di base (JSON non valido, tipi sbagliati, campo obbligatorio mancante).

Errore comune: Usarlo per tutto. Preferisci 401, 403, 404, 409 o 422 quando descrivono meglio il problema.

401 Unauthorized

L’autenticazione manca o non è valida (credenziali o token assenti o errati). Invia un header WWW-Authenticate.

Errore comune: Usarlo quando l’utente è noto ma non autorizzato: in quel caso è 403.

402 Payment Required

Riservato per usi futuri; alcune API lo usano per quote esaurite o piani non pagati.

Errore comune: Contare su un significato standard: non esiste.

403 Forbidden

Il server ha capito la richiesta e l’identità, ma rifiuta: il chiamante non ha i permessi.

Errore comune: Restituire 403 invece di 404 può rivelare che una risorsa esiste; scegli in modo consapevole.

404 Not Found

Nessuna risorsa a questo URL (oppure il server non vuole rivelare che esiste).

Errore comune: Usarlo per una lista vuota: una collezione senza elementi è 200 con [].

405 Method Not Allowed

L’URL esiste ma non per questo metodo. Invia un header Allow con l’elenco dei metodi validi.

Errore comune: Restituire 404 per un metodo sbagliato.

406 Not Acceptable

Il server non può produrre alcuna rappresentazione consentita dall’header Accept.

Errore comune: Ignorare Accept in silenzio.

408 Request Timeout

Il server ha smesso di aspettare che il client finisse di inviare la richiesta.

Errore comune: Usarlo quando è il tuo backend a essere lento: in quel caso è 504 o 503.

409 Conflict

La richiesta è in conflitto con lo stato attuale: valore univoco duplicato, versione non corrispondente, modifica di un elemento bloccato.

Errore comune: Usare 400 per i conflitti, così i client non capiscono cosa correggere.

410 Gone

La risorsa esisteva ed è stata rimossa in modo permanente, senza un indirizzo alternativo.

Errore comune: Usare 404 per una rimozione voluta e definitiva, che i client dovrebbero smettere di richiedere.

412 Precondition Failed

Una condizione come If-Match non è soddisfatta: la risorsa è cambiata da quando il client l’ha letta (optimistic locking).

Errore comune: Non supportare If-Match, il che porta ad aggiornamenti persi.

413 Content Too Large

Il body della richiesta è più grande di quanto il server accetti.

Errore comune: Chiudere la connessione senza una risposta.

415 Unsupported Media Type

Il Content-Type del body non è supportato (per esempio XML inviato a un endpoint che accetta solo JSON).

Errore comune: Restituire 400 senza dire quale tipo è atteso.

418 I'm a teapot

Definito in una RFC del pesce d’aprile (2324); non è un vero codice per API.

Errore comune: Usarlo per errori reali.

422 Unprocessable Content

Il JSON è ben formato ma il contenuto non è valido dal punto di vista semantico (una regola di business o di validazione non è rispettata).

Errore comune: Mescolare 400 e 422 in modo incoerente: scegli una convenzione per la validazione e documentala.

423 Locked

La risorsa è bloccata (WebDAV, RFC 4918).

Errore comune: Usarlo al di fuori della semantica dei lock.

425 Too Early

Il server non elaborerà una richiesta che potrebbe essere ripetuta (TLS early data).

Errore comune: Raramente serve nelle API applicative.

428 Precondition Required

Il server richiede una richiesta condizionale (per esempio If-Match) per evitare aggiornamenti persi (RFC 6585).

Errore comune: Consentire sovrascritture alla cieca.

429 Too Many Requests

Rate limit superato (RFC 6585). Invia Retry-After e, idealmente, gli header dei limiti.

Errore comune: Usare 503 per i rate limit, oppure non dire al client quando riprovare.

431 Request Header Fields Too Large

Gli header (spesso cookie o token) sono troppo grandi (RFC 6585).

Errore comune: Mettere grandi quantità di dati negli header.

451 Unavailable For Legal Reasons

L’accesso è negato per motivi legali (RFC 7725).

Errore comune: Usare 403 e nascondere la causa legale.

500 Internal Server Error

Un guasto imprevisto del server. Registralo nei log e restituisci un body generico con un id di correlazione.

Errore comune: Usarlo per errori del client, oppure esporre gli stack trace.

501 Not Implemented

Il server non supporta affatto il metodo o la funzionalità richiesta.

Errore comune: Usarlo per una funzionalità disattivata solo temporaneamente: usa 503.

502 Bad Gateway

Un gateway o un proxy ha ricevuto una risposta non valida dal server a monte.

Errore comune: Dare la colpa al client: guarda il servizio a monte.

503 Service Unavailable

Il server non è temporaneamente in grado di gestire le richieste (manutenzione, sovraccarico). Invia Retry-After.

Errore comune: Restituire 500 per una manutenzione programmata.

504 Gateway Timeout

Un gateway o un proxy non ha ricevuto in tempo una risposta dal server a monte.

Errore comune: Impostare i timeout in modo che i client rinuncino prima del gateway.

Come si usa

  1. Cerca per numero o per parola, oppure filtra per classe (2xx, 3xx, 4xx, 5xx).
  2. Leggi il significato del codice e l’errore più comune.
  3. Usa il link sul numero del codice per condividerlo.

Esempio

Cercando 429 vedi quando restituire Too Many Requests e che dovrebbe essere accompagnato da Retry-After. Confrontando 401 e 403 vedi la differenza tra "chi sei?" e "non puoi".

Limiti

È un riferimento per chi progetta API, non il registro completo. Le definizioni seguono la RFC 9110 e le RFC collegate; consultale per i casi limite.

Privacy e sicurezza di ciò che inserisci

Questa pagina non raccoglie nulla su ciò che cerchi; contiamo solo le visite anonime. Vedi l’informativa sulla privacy.

Stai progettando o correggendo una API?

Rivediamo contratti API, gestione degli errori, autenticazione e rate limit. Vedi la revisione di sicurezza (in inglese), oppure controlla una specifica con il controllo agent-readiness gratuito (in inglese).

Scrivici su LinkedIn