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.
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).
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.
Il server accetta di cambiare protocollo, per esempio verso WebSocket dopo una richiesta Upgrade.
Errore comune: Non è una risposta alle normali chiamate API.
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.
È 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.
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.
Successo senza body: tipico per DELETE e per PUT/PATCH che non restituiscono nulla.
Errore comune: Inviare un body con 204 (deve essere vuoto).
Una richiesta di intervallo è riuscita (header Range): usata per download ripristinabili e contenuti multimediali.
Errore comune: Ignorare Range e inviare sempre il file intero.
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.
Redirect temporaneo (storicamente ambiguo sul metodo).
Errore comune: Preferisci 303 o 307 per essere espliciti sul metodo.
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.
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.
Redirect temporaneo che mantiene metodo e body (una POST resta una POST).
Errore comune: Confonderlo con 302.
Redirect permanente che mantiene metodo e body.
Errore comune: Usare 301 in API dove una POST deve restare POST.
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.
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.
Riservato per usi futuri; alcune API lo usano per quote esaurite o piani non pagati.
Errore comune: Contare su un significato standard: non esiste.
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.
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 [].
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.
Il server non può produrre alcuna rappresentazione consentita dall’header Accept.
Errore comune: Ignorare Accept in silenzio.
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.
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.
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.
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.
Il body della richiesta è più grande di quanto il server accetti.
Errore comune: Chiudere la connessione senza una risposta.
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.
Definito in una RFC del pesce d’aprile (2324); non è un vero codice per API.
Errore comune: Usarlo per errori reali.
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.
La risorsa è bloccata (WebDAV, RFC 4918).
Errore comune: Usarlo al di fuori della semantica dei lock.
Il server non elaborerà una richiesta che potrebbe essere ripetuta (TLS early data).
Errore comune: Raramente serve nelle API applicative.
Il server richiede una richiesta condizionale (per esempio If-Match) per evitare aggiornamenti persi (RFC 6585).
Errore comune: Consentire sovrascritture alla cieca.
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.
Gli header (spesso cookie o token) sono troppo grandi (RFC 6585).
Errore comune: Mettere grandi quantità di dati negli header.
L’accesso è negato per motivi legali (RFC 7725).
Errore comune: Usare 403 e nascondere la causa legale.
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.
Il server non supporta affatto il metodo o la funzionalità richiesta.
Errore comune: Usarlo per una funzionalità disattivata solo temporaneamente: usa 503.
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.
Il server non è temporaneamente in grado di gestire le richieste (manutenzione, sovraccarico). Invia Retry-After.
Errore comune: Restituire 500 per una manutenzione programmata.
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.
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".
È 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.
Questa pagina non raccoglie nulla su ciò che cerchi; contiamo solo le visite anonime. Vedi l’informativa sulla privacy.
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