Web e marketing

Riferimento dei codici di stato HTTP

Cerca e impara il significato, la causa tipica e il caso d'uso di ogni codice di stato HTTP comune, con snippet in cURL/Python/JS/PHP.

100 Continue #

Una risposta interlocutoria che segnala che il server ha ricevuto gli header della richiesta e che il client può procedere a inviarne il body. Definito nella RFC 9110, sezione 15.2.1.

Causa comune

Il client ha inviato un header Expect: 100-continue per verificare se il server accetterà un body di grandi dimensioni prima di trasmetterlo.

Quando usarlo

Usato tra gli header e il body di upload lunghi (PUT, POST), così il client non spreca banda su una richiesta che il server rifiuterebbe.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 100 Continue

import requests
r = requests.get("https://example.com/path")
if r.status_code == 100:
    print("Continue")

const r = await fetch("https://example.com/path");
if (r.status === 100) {
  console.log("Continue");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 100);
// or:
http_response_code(100);

101 Switching Protocols #

Il server accetta di passare a un protocollo applicativo diverso sulla stessa connessione TCP, indicato nell'header Upgrade. RFC 9110 §15.2.2.

Causa comune

Il client ha richiesto un Upgrade (di solito a WebSocket o HTTP/2 su h2c) e il server l'ha accettato.

Quando usarlo

Oggi il caso prevalente è l'handshake WebSocket. Dopo un 101 la connessione non è più HTTP.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 101 Switching Protocols

import requests
r = requests.get("https://example.com/path")
if r.status_code == 101:
    print("Switching Protocols")

const r = await fetch("https://example.com/path");
if (r.status === 101) {
  console.log("Switching Protocols");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 101);
// or:
http_response_code(101);

200 OK #

Risposta di successo standard — la richiesta è andata a buon fine e il body della risposta contiene la rappresentazione richiesta. RFC 9110 §15.3.1.

Causa comune

La richiesta era valida, autorizzata e soddisfatta senza redirect.

Quando usarlo

GET che restituiscono dati, POST/PUT elaborate inline e non in modo asincrono, risposte API in salute.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 200 OK

import requests
r = requests.get("https://example.com/path")
if r.status_code == 200:
    print("OK")

const r = await fetch("https://example.com/path");
if (r.status === 200) {
  console.log("OK");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 200);
// or:
http_response_code(200);

201 Created #

La richiesta è andata a buon fine e ne è risultata la creazione di una nuova risorsa. L'header Location DOVREBBE puntare alla nuova risorsa. RFC 9110 §15.3.2.

Causa comune

Una POST o una PUT ha creato una risorsa (riga di database, file, utente, ecc.).

Quando usarlo

Da usare dopo aver creato risorse REST. Restituisci la nuova rappresentazione nel body e un header Location.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 201 Created

import requests
r = requests.get("https://example.com/path")
if r.status_code == 201:
    print("Created")

const r = await fetch("https://example.com/path");
if (r.status === 201) {
  console.log("Created");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 201);
// or:
http_response_code(201);

202 Accepted #

La richiesta è stata accettata per l'elaborazione, ma non è ancora completa. Potrà andare a buon fine o fallire in seguito. RFC 9110 §15.3.3.

Causa comune

L'elaborazione asincrona è stata accodata. Il lavoro avverrà più tardi.

Quando usarlo

Job in background, endpoint di import batch, qualunque cosa che restituisca un URL di stato del job mentre il lavoro è ancora in corso.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 202 Accepted

import requests
r = requests.get("https://example.com/path")
if r.status_code == 202:
    print("Accepted")

const r = await fetch("https://example.com/path");
if (r.status === 202) {
  console.log("Accepted");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 202);
// or:
http_response_code(202);

204 No Content #

La richiesta è andata a buon fine; la risposta è volutamente senza body. Gli header possono trasportare metadati. RFC 9110 §15.3.5.

Causa comune

Un update o una delete che non hanno bisogno di restituire una rappresentazione.

Quando usarlo

Risposte a DELETE, PUT/PATCH dove il client ha già la nuova rappresentazione, endpoint "salva e resta".

curl -i -X HEAD https://example.com/path
# HTTP/1.1 204 No Content

import requests
r = requests.get("https://example.com/path")
if r.status_code == 204:
    print("No Content")

const r = await fetch("https://example.com/path");
if (r.status === 204) {
  console.log("No Content");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 204);
// or:
http_response_code(204);

206 Partial Content #

Il server ha restituito solo una parte della rappresentazione in risposta a una richiesta Range. RFC 9110 §15.3.7.

Causa comune

Il client ha richiesto un intervallo di byte tramite l'header Range.

Quando usarlo

Download ripristinabili, streaming video con seek, e download paralleli a chunk.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 206 Partial Content

import requests
r = requests.get("https://example.com/path")
if r.status_code == 206:
    print("Partial Content")

const r = await fetch("https://example.com/path");
if (r.status === 206) {
  console.log("Partial Content");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 206);
// or:
http_response_code(206);

301 Moved Permanently #

La risorsa di destinazione ha un nuovo URI permanente. I client DOVREBBERO aggiornare i segnalibri e i motori di ricerca aggiornano i loro indici. RFC 9110 §15.4.2.

Causa comune

Cambio di URL canonico — rinomina del dominio, correzione di slug, migrazione a HTTPS.

Quando usarlo

Redirect a lungo termine. Evita il 301 per redirect di breve durata, perché client e intermediari fanno cache aggressiva.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 301 Moved Permanently

import requests
r = requests.get("https://example.com/path")
if r.status_code == 301:
    print("Moved Permanently")

const r = await fetch("https://example.com/path");
if (r.status === 301) {
  console.log("Moved Permanently");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 301);
// or:
http_response_code(301);

302 Found #

La risorsa di destinazione risiede temporaneamente a un URI diverso. I client dovrebbero richiedere il nuovo URI senza cambiare la semantica del metodo, ma storicamente molti riscrivono POST in GET. RFC 9110 §15.4.3.

Causa comune

Redirect temporaneo con un comportamento bizzarro di riscrittura del metodo, mantenuto per compatibilità con il legacy.

Quando usarlo

Percorsi legacy. Nelle nuove API preferisci 303 o 307 per essere inequivocabili sulla gestione del metodo.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 302 Found

import requests
r = requests.get("https://example.com/path")
if r.status_code == 302:
    print("Found")

const r = await fetch("https://example.com/path");
if (r.status === 302) {
  console.log("Found");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 302);
// or:
http_response_code(302);

303 See Other #

Reindirizza a una risorsa che va recuperata con GET, qualunque fosse il metodo originale. RFC 9110 §15.4.4.

Causa comune

Dopo una POST non idempotente, il server manda il client su una pagina di conferma o su una risorsa appena creata.

Quando usarlo

Pattern Post/Redirect/Get. Riscrive sempre in GET, quindi è sicuro dopo l'invio di un form.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 303 See Other

import requests
r = requests.get("https://example.com/path")
if r.status_code == 303:
    print("See Other")

const r = await fetch("https://example.com/path");
if (r.status === 303) {
  console.log("See Other");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 303);
// or:
http_response_code(303);

304 Not Modified #

La rappresentazione in cache che il client ha già è ancora valida; non viene inviato alcun body. RFC 9110 §15.4.5.

Causa comune

Il client ha inviato If-None-Match o If-Modified-Since e i validatori corrispondevano alla risorsa attuale.

Quando usarlo

Risposte a GET condizionali per la cache. Risparmia banda su asset statici e risposte API non modificate.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 304 Not Modified

import requests
r = requests.get("https://example.com/path")
if r.status_code == 304:
    print("Not Modified")

const r = await fetch("https://example.com/path");
if (r.status === 304) {
  console.log("Not Modified");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 304);
// or:
http_response_code(304);

307 Temporary Redirect #

Come il 302, ma preserva esplicitamente metodo e body della richiesta. RFC 9110 §15.4.8.

Causa comune

Un redirect a breve termine in cui la POST/PUT originale deve essere riemessa al nuovo URI.

Quando usarlo

Redirect di manutenzione, routing A/B o redirect geografici che devono mantenere il metodo originale.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 307 Temporary Redirect

import requests
r = requests.get("https://example.com/path")
if r.status_code == 307:
    print("Temporary Redirect")

const r = await fetch("https://example.com/path");
if (r.status === 307) {
  console.log("Temporary Redirect");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 307);
// or:
http_response_code(307);

308 Permanent Redirect #

Come il 301, ma preserva esplicitamente metodo e body della richiesta. RFC 9110 §15.4.9.

Causa comune

Cambio di URI canonico per metodi non-GET (upgrade a HTTPS per API POST, rinomine di rotte).

Quando usarlo

Redirect permanenti per API REST. Da usare al posto del 301 quando il metodo originale non deve essere riscritto.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 308 Permanent Redirect

import requests
r = requests.get("https://example.com/path")
if r.status_code == 308:
    print("Permanent Redirect")

const r = await fetch("https://example.com/path");
if (r.status === 308) {
  console.log("Permanent Redirect");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 308);
// or:
http_response_code(308);

400 Bad Request #

Il server non riesce a elaborare la richiesta a causa di un errore del client: sintassi malformata, framing non valido, routing ingannevole. RFC 9110 §15.5.1.

Causa comune

JSON malformato, campo obbligatorio mancante, header malformato, cookie sovradimensionato.

Quando usarlo

Fallback generico per errori del client. Quando si applicano, preferisci codici più specifici (422, 411, 415).

curl -i -X HEAD https://example.com/path
# HTTP/1.1 400 Bad Request

import requests
r = requests.get("https://example.com/path")
if r.status_code == 400:
    print("Bad Request")

const r = await fetch("https://example.com/path");
if (r.status === 400) {
  console.log("Bad Request");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 400);
// or:
http_response_code(400);

401 Unauthorized #

Alla richiesta mancano credenziali di autenticazione valide. La risposta DEVE includere un header WWW-Authenticate che elenchi gli schemi accettati. RFC 9110 §15.5.2.

Causa comune

Token mancante, scaduto o non valido; nessun header Authorization dove ne è richiesto uno.

Quando usarlo

Endpoint API protetti da autenticazione. Distinto dal 403 — 401 significa "non autenticato", 403 significa "autenticato ma non autorizzato".

curl -i -X HEAD https://example.com/path
# HTTP/1.1 401 Unauthorized

import requests
r = requests.get("https://example.com/path")
if r.status_code == 401:
    print("Unauthorized")

const r = await fetch("https://example.com/path");
if (r.status === 401) {
  console.log("Unauthorized");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 401);
// or:
http_response_code(401);

403 Forbidden #

Il server ha capito la richiesta ma rifiuta di autorizzarla. RFC 9110 §15.5.4.

Causa comune

L'utente è autenticato ma non ha il permesso, oppure la risorsa è bloccata per l'IP / la regione dell'utente.

Quando usarlo

Fallimenti di autorizzazione, allowlist di IP, controlli di accesso basati sul ruolo.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 403 Forbidden

import requests
r = requests.get("https://example.com/path")
if r.status_code == 403:
    print("Forbidden")

const r = await fetch("https://example.com/path");
if (r.status === 403) {
  console.log("Forbidden");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 403);
// or:
http_response_code(403);

404 Not Found #

Il server non trova una rappresentazione attuale della risorsa di destinazione. Può essere usato anche per nascondere un 403. RFC 9110 §15.5.5.

Causa comune

URL con refuso, risorsa eliminata, oppure risorsa che non è mai esistita.

Quando usarlo

Risposta predefinita per rotte e risorse mancanti. Mette in cache meno aggressivamente del 410.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 404 Not Found

import requests
r = requests.get("https://example.com/path")
if r.status_code == 404:
    print("Not Found")

const r = await fetch("https://example.com/path");
if (r.status === 404) {
  console.log("Not Found");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 404);
// or:
http_response_code(404);

405 Method Not Allowed #

Il metodo non è supportato sulla risorsa. La risposta DEVE includere un header Allow che elenchi i metodi supportati. RFC 9110 §15.5.6.

Causa comune

Chiamare DELETE su una collezione di sola lettura, POST su una risorsa singleton, ecc.

Quando usarlo

API REST che vogliono essere esplicite sui verbi consentiti.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 405 Method Not Allowed

import requests
r = requests.get("https://example.com/path")
if r.status_code == 405:
    print("Method Not Allowed")

const r = await fetch("https://example.com/path");
if (r.status === 405) {
  console.log("Method Not Allowed");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 405);
// or:
http_response_code(405);

406 Not Acceptable #

Il server non può produrre una rappresentazione conforme agli header Accept-*. RFC 9110 §15.5.7.

Causa comune

Il client ha chiesto application/xml ma è disponibile solo application/json.

Quando usarlo

Negoziazione del contenuto rigorosa. Molte API ripiegano su JSON invece di restituire 406.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 406 Not Acceptable

import requests
r = requests.get("https://example.com/path")
if r.status_code == 406:
    print("Not Acceptable")

const r = await fetch("https://example.com/path");
if (r.status === 406) {
  console.log("Not Acceptable");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 406);
// or:
http_response_code(406);

408 Request Timeout #

Il server ha smesso di attendere che il client completasse la richiesta. RFC 9110 §15.5.9.

Causa comune

Connessione client lenta, upload incompleto, keep-alive inattivo che ha superato il timeout del server.

Quando usarlo

Reverse proxy e load balancer davanti a client lenti.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 408 Request Timeout

import requests
r = requests.get("https://example.com/path")
if r.status_code == 408:
    print("Request Timeout")

const r = await fetch("https://example.com/path");
if (r.status === 408) {
  console.log("Request Timeout");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 408);
// or:
http_response_code(408);

409 Conflict #

La richiesta è in conflitto con lo stato attuale della risorsa. RFC 9110 §15.5.10.

Causa comune

Due client hanno modificato in concorrenza lo stesso record; violazione di un vincolo di unicità; PUT con un ETag obsoleto.

Quando usarlo

Controllo della concorrenza ottimistico, endpoint di create idempotenti.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 409 Conflict

import requests
r = requests.get("https://example.com/path")
if r.status_code == 409:
    print("Conflict")

const r = await fetch("https://example.com/path");
if (r.status === 409) {
  console.log("Conflict");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 409);
// or:
http_response_code(409);

410 Gone #

La risorsa è stata rimossa intenzionalmente e non tornerà. RFC 9110 §15.5.11.

Causa comune

Contenuto eliminato definitivamente; endpoint API deprecato che è stato dismesso.

Quando usarlo

Pagine rimosse di cui vuoi che i crawler abbandonino l'URL più in fretta di un 404.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 410 Gone

import requests
r = requests.get("https://example.com/path")
if r.status_code == 410:
    print("Gone")

const r = await fetch("https://example.com/path");
if (r.status === 410) {
  console.log("Gone");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 410);
// or:
http_response_code(410);

411 Length Required #

Alla richiesta manca un header Content-Length dove il server lo richiede. RFC 9110 §15.5.12.

Causa comune

Un client in streaming che non ha bufferizzato il body o non ha usato il chunked transfer encoding.

Quando usarlo

Server che non consentono upload chunked su determinati endpoint.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 411 Length Required

import requests
r = requests.get("https://example.com/path")
if r.status_code == 411:
    print("Length Required")

const r = await fetch("https://example.com/path");
if (r.status === 411) {
  console.log("Length Required");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 411);
// or:
http_response_code(411);

413 Content Too Large #

Il body della richiesta è più grande di quanto il server sia disposto ad accettare. RFC 9110 §15.5.14. Rinominato da "Payload Too Large" nella RFC 9110.

Causa comune

Upload oltre il limite di dimensione configurato, file oltre la dimensione massima del form.

Quando usarlo

Endpoint di upload file, API JSON con limiti sulla dimensione del body.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 413 Content Too Large

import requests
r = requests.get("https://example.com/path")
if r.status_code == 413:
    print("Content Too Large")

const r = await fetch("https://example.com/path");
if (r.status === 413) {
  console.log("Content Too Large");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 413);
// or:
http_response_code(413);

414 URI Too Long #

L'URI della richiesta è più lungo di quanto il server sia disposto a interpretare. RFC 9110 §15.5.15.

Causa comune

Query string enormi (spesso da form inviati con method=GET) o token incorporati nell'URL.

Quando usarlo

Quando gli utenti raggiungono il tuo endpoint con URL anormalmente lunghi — passa il form a POST.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 414 URI Too Long

import requests
r = requests.get("https://example.com/path")
if r.status_code == 414:
    print("URI Too Long")

const r = await fetch("https://example.com/path");
if (r.status === 414) {
  console.log("URI Too Long");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 414);
// or:
http_response_code(414);

415 Unsupported Media Type #

Il server rifiuta di accettare il body nel formato descritto dall'header Content-Type. RFC 9110 §15.5.16.

Causa comune

Inviare application/xml a un endpoint che accetta solo JSON, Content-Type mancante o sbagliato.

Quando usarlo

API REST che accettano rigorosamente solo uno o due media type.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 415 Unsupported Media Type

import requests
r = requests.get("https://example.com/path")
if r.status_code == 415:
    print("Unsupported Media Type")

const r = await fetch("https://example.com/path");
if (r.status === 415) {
  console.log("Unsupported Media Type");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 415);
// or:
http_response_code(415);

418 I'm a teapot #

Uno scherzo del primo aprile dalla RFC 2324 (HTCPCP). Alcuni server lo restituiscono come errore generico "rifiuto di preparare". Non è uno status di produzione reale.

Causa comune

Software che restituisce 418 di proposito, spesso per segnalare trappole anti-abuso o per scherzo.

Quando usarlo

Solo per easter egg. Non usarlo in API reali — molti proxy e client non lo riconoscono.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 418 I'm a teapot

import requests
r = requests.get("https://example.com/path")
if r.status_code == 418:
    print("I'm a teapot")

const r = await fetch("https://example.com/path");
if (r.status === 418) {
  console.log("I'm a teapot");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 418);
// or:
http_response_code(418);

422 Unprocessable Content #

La sintassi va bene, ma il server non può elaborare il contenuto semantico. RFC 9110 §15.5.21. Originariamente introdotto da WebDAV (RFC 4918).

Causa comune

Errori di validazione su un payload JSON sintatticamente valido — campo obbligatorio vuoto, valore fuori intervallo.

Quando usarlo

Validazione dei form nelle API moderne. Più pulito del 400 perché la richiesta è sintatticamente valida.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 422 Unprocessable Content

import requests
r = requests.get("https://example.com/path")
if r.status_code == 422:
    print("Unprocessable Content")

const r = await fetch("https://example.com/path");
if (r.status === 422) {
  console.log("Unprocessable Content");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 422);
// or:
http_response_code(422);

423 Locked #

La risorsa è bloccata. RFC 4918 (WebDAV).

Causa comune

Risorsa WebDAV su cui un altro utente detiene un lock esclusivo.

Quando usarlo

Server di collaborazione su documenti, front-end di controllo di versione.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 423 Locked

import requests
r = requests.get("https://example.com/path")
if r.status_code == 423:
    print("Locked")

const r = await fetch("https://example.com/path");
if (r.status === 423) {
  console.log("Locked");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 423);
// or:
http_response_code(423);

425 Too Early #

Il server non vuole elaborare una richiesta che potrebbe essere riprodotta, di solito perché inviata in TLS 1.3 0-RTT (early data). RFC 8470.

Causa comune

Richiesta TLS 1.3 0-RTT che il server considera non sicura rispetto al replay.

Quando usarlo

Per proteggere endpoint non idempotenti dal replay durante gli handshake 0-RTT.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 425 Too Early

import requests
r = requests.get("https://example.com/path")
if r.status_code == 425:
    print("Too Early")

const r = await fetch("https://example.com/path");
if (r.status === 425) {
  console.log("Too Early");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 425);
// or:
http_response_code(425);

428 Precondition Required #

Il server di origine richiede che la richiesta sia condizionale. RFC 6585.

Causa comune

Il server vuole che i client usino If-Match / If-Unmodified-Since per evitare conflitti da lost-update.

Quando usarlo

API con locking ottimistico che rifiutano scritture incondizionate.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 428 Precondition Required

import requests
r = requests.get("https://example.com/path")
if r.status_code == 428:
    print("Precondition Required")

const r = await fetch("https://example.com/path");
if (r.status === 428) {
  console.log("Precondition Required");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 428);
// or:
http_response_code(428);

429 Too Many Requests #

L'utente ha inviato troppe richieste in un dato intervallo di tempo. RFC 6585.

Causa comune

Limite di rate raggiunto; la risposta di solito include un header Retry-After.

Quando usarlo

API con rate-limit, throttling sul login, mitigazione di abusi.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 429 Too Many Requests

import requests
r = requests.get("https://example.com/path")
if r.status_code == 429:
    print("Too Many Requests")

const r = await fetch("https://example.com/path");
if (r.status === 429) {
  console.log("Too Many Requests");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 429);
// or:
http_response_code(429);

431 Request Header Fields Too Large #

Il server rifiuta di elaborare la richiesta perché i suoi header sono troppo grandi. RFC 6585.

Causa comune

Un cookie sovradimensionato, un Referer o un Authorization estremamente lunghi.

Quando usarlo

Quando i cookie di sessione superano il buffer del reverse proxy; valuta di accorciarli o di spostare lo stato nel body.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 431 Request Header Fields Too Large

import requests
r = requests.get("https://example.com/path")
if r.status_code == 431:
    print("Request Header Fields Too Large")

const r = await fetch("https://example.com/path");
if (r.status === 431) {
  console.log("Request Header Fields Too Large");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 431);
// or:
http_response_code(431);

451 Unavailable For Legal Reasons #

La risorsa non è disponibile per ragioni legali — un'ingiunzione di rimozione, un geo-blocco o un DMCA. RFC 7725.

Causa comune

Ordinanza giudiziaria, takedown del regolatore, risposta al diritto all'oblio GDPR.

Quando usarlo

Team di compliance che devono essere trasparenti sul perché una pagina è bloccata.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 451 Unavailable For Legal Reasons

import requests
r = requests.get("https://example.com/path")
if r.status_code == 451:
    print("Unavailable For Legal Reasons")

const r = await fetch("https://example.com/path");
if (r.status === 451) {
  console.log("Unavailable For Legal Reasons");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 451);
// or:
http_response_code(451);

500 Internal Server Error #

Il server ha incontrato una condizione inattesa che gli ha impedito di evadere la richiesta. RFC 9110 §15.6.1.

Causa comune

Eccezione non gestita, bug applicativo, dipendenza guasta, query fuori controllo.

Quando usarlo

Errore catch-all del server. Logga sempre uno stack trace e un request ID che gli utenti possano citare.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 500 Internal Server Error

import requests
r = requests.get("https://example.com/path")
if r.status_code == 500:
    print("Internal Server Error")

const r = await fetch("https://example.com/path");
if (r.status === 500) {
  console.log("Internal Server Error");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 500);
// or:
http_response_code(500);

501 Not Implemented #

Il server non supporta la funzionalità richiesta per evadere la richiesta. RFC 9110 §15.6.2.

Causa comune

Metodo sconosciuto, feature flag disattivata, percorso di codice abbozzato.

Quando usarlo

Endpoint API che esistono ma non sono ancora costruiti. Preferisci 405 se è il metodo a essere sbagliato ma altri funzionano.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 501 Not Implemented

import requests
r = requests.get("https://example.com/path")
if r.status_code == 501:
    print("Not Implemented")

const r = await fetch("https://example.com/path");
if (r.status === 501) {
  console.log("Not Implemented");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 501);
// or:
http_response_code(501);

502 Bad Gateway #

Il gateway o il proxy ha ricevuto una risposta non valida dal server upstream. RFC 9110 §15.6.3.

Causa comune

L'upstream ha restituito HTTP malformato, la connessione si è interrotta a metà risposta o l'applicazione è andata in crash.

Quando usarlo

Reverse proxy (Nginx, Cloudflare, ALB) quando l'applicazione che hanno dietro fallisce.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 502 Bad Gateway

import requests
r = requests.get("https://example.com/path")
if r.status_code == 502:
    print("Bad Gateway")

const r = await fetch("https://example.com/path");
if (r.status === 502) {
  console.log("Bad Gateway");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 502);
// or:
http_response_code(502);

503 Service Unavailable #

Il server al momento non è in grado di gestire la richiesta, di solito per manutenzione o sovraccarico. RFC 9110 §15.6.4.

Causa comune

Finestra di manutenzione, coda piena, autoscaler in ritardo, brown-out volontario.

Quando usarlo

Downtime pianificato o protezione da sovraccarico. Imposta sempre Retry-After così i client possono indietreggiare.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 503 Service Unavailable

import requests
r = requests.get("https://example.com/path")
if r.status_code == 503:
    print("Service Unavailable")

const r = await fetch("https://example.com/path");
if (r.status === 503) {
  console.log("Service Unavailable");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 503);
// or:
http_response_code(503);

504 Gateway Timeout #

Il gateway o il proxy non ha ricevuto una risposta tempestiva dal server upstream. RFC 9110 §15.6.5.

Causa comune

L'upstream ha impiegato più del timeout configurato del proxy per rispondere.

Quando usarlo

Codice applicativo lento, query di database bloccate, API di terze parti che si impallano.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 504 Gateway Timeout

import requests
r = requests.get("https://example.com/path")
if r.status_code == 504:
    print("Gateway Timeout")

const r = await fetch("https://example.com/path");
if (r.status === 504) {
  console.log("Gateway Timeout");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 504);
// or:
http_response_code(504);

505 HTTP Version Not Supported #

Il server non supporta la versione major HTTP della richiesta. RFC 9110 §15.6.6.

Causa comune

Il client parla HTTP/2 con un server che fa solo HTTP/1.0, oppure invia un token di versione non riconosciuto.

Quando usarlo

Raro nella pratica. Edge mal configurati o client molto datati.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 505 HTTP Version Not Supported

import requests
r = requests.get("https://example.com/path")
if r.status_code == 505:
    print("HTTP Version Not Supported")

const r = await fetch("https://example.com/path");
if (r.status === 505) {
  console.log("HTTP Version Not Supported");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 505);
// or:
http_response_code(505);

511 Network Authentication Required #

Il client deve autenticarsi per usare la rete — di solito un captive portal. RFC 6585.

Causa comune

Wi-Fi di un albergo o di un aeroporto che intercetta il traffico fino al login.

Quando usarlo

Captive portal su reti temporanee. I server normalmente non lo restituiscono da soli.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 511 Network Authentication Required

import requests
r = requests.get("https://example.com/path")
if r.status_code == 511:
    print("Network Authentication Required")

const r = await fetch("https://example.com/path");
if (r.status === 511) {
  console.log("Network Authentication Required");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 511);
// or:
http_response_code(511);

Cosa sono i codici di stato HTTP?

Un codice di stato HTTP è il numero di tre cifre che il server restituisce all'inizio di ogni risposta. Si raggruppa in cinque famiglie: 1xx informativi, 2xx successo, 3xx redirezione, 4xx errore client e 5xx errore server. I codici sono definiti nella RFC 9110 (la specifica consolidata del 2022 che sostituisce la vecchia serie 7230-7235), con estensioni nella RFC 6585 (4xx/5xx aggiuntivi), RFC 7725 (451), RFC 4918 (WebDAV) e RFC 8470 (425). Leggere correttamente lo status fa la differenza tra risolvere un bug in cinque minuti e inseguire un fantasma per un pomeriggio: un 404 dalla CDN significa che il path è sbagliato, un 502 dal proxy significa che l'applicazione è andata in crash, e un 401 senza header WWW-Authenticate è un backend mal configurato. Questa pagina è un cheat sheet ricercabile — ogni scheda include il nome ufficiale, una descrizione fondata sulle RFC, la causa tipica e snippet di codice concreti che puoi incollare in curl, Python, JavaScript o PHP.

Come usare il riferimento

Scrivi un codice o parte di un nome nella casella di ricerca, oppure filtra per famiglia con le linguette. Ogni scheda si apre per rivelare la descrizione tecnica, le cause comuni e uno snippet con linguette che puoi adattare. Ogni codice ha la sua ancora (es. #404), così puoi linkare profondamente la documentazione del team direttamente a uno status specifico.

Le famiglie dei codici di stato a colpo d'occhio

Intervallo	Famiglia	Significato
1xx	Informazioni	Risposte provvisorie; raramente visibili al livello applicativo.
2xx	Successo	La richiesta è stata ricevuta, capita e accettata.
3xx	Redirezione	Serve un'azione ulteriore (un URL diverso, una validazione di cache, ecc.).
4xx	Errore client	La richiesta aveva un problema (input errato, autenticazione mancante, metodo sbagliato).
5xx	Errore server	Il server non è riuscito a evadere una richiesta apparentemente valida.

Domande frequenti

Da dove arrivano questi codici?

La RFC 9110 è la specifica canonica del 2022 che consolida la vecchia serie RFC 7231. Codici aggiuntivi vivono nelle RFC 6585 (428, 429, 431, 511), RFC 7725 (451), RFC 4918 (WebDAV) e RFC 8470 (425).

Devo usare 401 o 403?

401 significa "non sei autenticato". 403 significa "sei autenticato ma non autorizzato". Un 401 deve includere un header WWW-Authenticate con gli schemi accettati; un 403 non dovrebbe, perché il problema non sono le credenziali.

Qual è la differenza tra 301 e 308?

Entrambi segnalano un redirect permanente. Storicamente il 301 in molti client riscrive POST in GET, mentre il 308 preserva esplicitamente metodo e body. Nelle nuove API usa 308.

Quando la mia CDN restituisce 502 e quando 504?

502 (Bad Gateway) vuol dire che l'upstream ha restituito dati malformati o ha chiuso la connessione. 504 (Gateway Timeout) vuol dire che l'upstream ci ha messo troppo. CloudFront, Cloudflare e Nginx li etichettano in modo diverso nei log — entrambi indicano un problema applicativo.

Per i contenuti eliminati devo restituire 404 o 410?

Usa 410 quando la risorsa è stata rimossa intenzionalmente e in modo permanente e vuoi che i crawler la abbandonino in fretta. 404 va bene per refusi e contenuti che potrebbero tornare; è anche una risposta difendibile per risorse di cui non vuoi confermare l'esistenza.

Gli snippet sono sicuri da copiare?

Sono template minimi pensati per essere letti e adattati. Nel tuo codice valida sempre l'input, gestisci gli errori e rispetta la semantica HTTP — gli esempi le saltano per brevità.