Introduzione

I codici di stato HTTP sono un elemento fondamentale del protocollo che governa le comunicazioni sul web. Ogni volta che un browser richiede una risorsa da un server web, quest'ultimo risponde con un codice di stato che indica l'esito della richiesta. Questi codici forniscono informazioni preziose sia agli utenti finali (anche se spesso indirettamente) che agli sviluppatori, aiutando a diagnosticare problemi e a comprendere il comportamento delle applicazioni web.

Conoscere in modo approfondito i codici di stato HTTP è essenziale per qualsiasi sviluppatore web. Che tu stia costruendo API, debuggando problemi di comunicazione o ottimizzando le prestazioni del tuo sito, una solida comprensione di questi codici ti permetterà di:

Diagnosticare rapidamente problemi di comunicazione client-server
Progettare API RESTful intuitive e conformi agli standard
Implementare correttamente reindirizzamenti e gestione degli errori
Migliorare l'esperienza utente durante situazioni problematiche

In questo articolo, esploreremo l'intero spettro dei codici di stato HTTP, dalle risposte informative (1xx) ai successi (2xx), dai reindirizzamenti (3xx) agli errori client (4xx) e server (5xx). Per ogni categoria, forniremo una spiegazione chiara dei codici più comuni e alcuni esempi pratici di quando potresti incontrarli o utilizzarli nelle tue applicazioni.

Panoramica delle categorie di codici di stato HTTP

I codici di stato HTTP sono numeri a tre cifre, dove la prima cifra definisce la classe di risposta. Ecco una panoramica delle cinque classi principali:

1xx (Informativo): La richiesta è stata ricevuta e il processo continua
2xx (Successo): La richiesta è stata ricevuta, compresa e accettata con successo
3xx (Reindirizzamento): Sono necessarie ulteriori azioni per completare la richiesta
4xx (Errore del client): La richiesta contiene una sintassi errata o non può essere soddisfatta
5xx (Errore del server): Il server non è riuscito a soddisfare una richiesta apparentemente valida

Ogni codice ha un significato specifico e standardizzato definito nelle specifiche HTTP, principalmente nelle RFC (Request for Comments) 7231, 7232, 7233, 7234, e 7235, che hanno aggiornato e sostituito la precedente RFC 2616.

Codici 1xx - Risposte informative

I codici di stato 1xx sono risposte informative che indicano che la richiesta è stata ricevuta e che il processo è in corso. Questi codici sono relativamente rari nella pratica quotidiana rispetto ad altre categorie.

100 Continue

Indica che il server ha ricevuto gli header della richiesta e che il client dovrebbe procedere a inviare il corpo della richiesta (nel caso di richieste che richiedono un corpo, come POST). Questo codice è utilizzato principalmente per ottimizzare la comunicazione quando si trasferiscono grandi quantità di dati.

Esempio di utilizzo:

POST /upload HTTP/1.1
Host: esempio.com
Content-Length: 5000000
Expect: 100-continue

// Il server risponde con:
HTTP/1.1 100 Continue

// Il client procede quindi a inviare il corpo

101 Switching Protocols

Indica che il server accetta la richiesta del client di passare a un protocollo diverso specificato nell'header Upgrade della richiesta. Questo è comunemente usato per passare da HTTP a WebSocket.

Esempio:

GET /chat HTTP/1.1
Host: esempio.com
Upgrade: websocket
Connection: Upgrade

// Il server risponde con:
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade

102 Processing (WebDAV)

Indica che il server ha ricevuto e sta elaborando la richiesta, ma non è ancora disponibile una risposta. Questo evita che il client vada in timeout per operazioni di lunga durata.

103 Early Hints

Permette al server di inviare header di risposta prima della risposta HTTP finale, principalmente per consentire al client di precaricare risorse mentre il server prepara la risposta completa.

Codici 2xx - Operazioni di successo

I codici di stato 2xx indicano che la richiesta del client è stata ricevuta, compresa e accettata con successo. Questi sono i codici che ogni sviluppatore spera di vedere nella maggior parte delle interazioni.

200 OK

Il codice più comune e desiderato. Indica che la richiesta è stata elaborata con successo. La risposta conterrà il contenuto richiesto.

GET /articoli/123 HTTP/1.1
Host: esempio.com

// Il server risponde con:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 234

{"id": 123, "titolo": "Codici di errore HTTP", "autore": "Edoardo Midali"}

201 Created

Indica che la richiesta ha portato alla creazione di una nuova risorsa. Tipicamente utilizzato come risposta alle richieste POST o PUT che creano nuovi record.

POST /articoli HTTP/1.1
Host: esempio.com
Content-Type: application/json

{"titolo": "Nuovo articolo", "contenuto": "Testo dell'articolo"}

// Il server risponde con:
HTTP/1.1 201 Created
Location: /articoli/456
Content-Type: application/json

{"id": 456, "titolo": "Nuovo articolo", "creato": "2025-03-15T10:30:00Z"}

202 Accepted

Indica che la richiesta è stata accettata per l'elaborazione, ma l'elaborazione non è ancora completata. Utile per operazioni asincrone o processi in background.

203 Non-Authoritative Information

Simile a 200 OK, ma indica che i metadati restituiti non sono esattamente quelli disponibili sul server di origine, ma sono stati raccolti da una copia locale o da una terza parte.

204 No Content

Indica che la richiesta è stata elaborata con successo, ma non c'è contenuto da restituire. Spesso utilizzato per operazioni DELETE o per richieste che richiedono solo un'azione senza output.

DELETE /articoli/123 HTTP/1.1
Host: esempio.com

// Il server risponde con:
HTTP/1.1 204 No Content

205 Reset Content

Simile a 204, ma indica al client di resettare la vista del documento, utile per form che devono essere svuotati dopo l'invio.

206 Partial Content

Indica che il server sta consegnando solo parte della risorsa a causa di un header Range inviato dal client. Utilizzato per riprendere download interrotti o per streaming di contenuti multimediali.

GET /video.mp4 HTTP/1.1
Host: esempio.com
Range: bytes=1024-2047

// Il server risponde con:
HTTP/1.1 206 Partial Content
Content-Range: bytes 1024-2047/10240
Content-Length: 1024

... contenuto parziale ...

207 Multi-Status (WebDAV)

Fornisce informazioni su più risorse, in situazioni in cui potrebbero essere appropriate più codici di stato.

208 Already Reported (WebDAV)

Utilizzato all'interno di un elemento DAV: propstat per evitare l'enumerazione ripetuta dello stesso stato interno.

226 IM Used (HTTP Delta encoding)

Il server ha soddisfatto una richiesta GET per la risorsa e la risposta è una rappresentazione del risultato di una o più manipolazioni di istanza applicate alla istanza corrente.

Codici 3xx - Reindirizzamenti

I codici di stato 3xx indicano che sono necessarie ulteriori azioni per completare la richiesta. Questi codici vengono utilizzati principalmente per i reindirizzamenti, informando il client che la risorsa richiesta si trova in un'altra posizione.

300 Multiple Choices

Indica che la risorsa richiesta ha più rappresentazioni, ciascuna con la propria specifica posizione. Il client dovrebbe scegliere una delle opzioni.

301 Moved Permanently

Indica che la risorsa richiesta è stata spostata permanentemente in una nuova posizione. I client dovrebbero aggiornare i loro segnalibri e riferimenti.

GET /vecchio-url HTTP/1.1
Host: esempio.com

// Il server risponde con:
HTTP/1.1 301 Moved Permanently
Location: https://esempio.com/nuovo-url

302 Found (precedentemente "Moved Temporarily")

Indica che la risorsa è temporaneamente disponibile in un'altra posizione, ma il client dovrebbe continuare a utilizzare l'URI originale per richieste future.

303 See Other

Utilizzato principalmente dopo un'operazione POST, indica al client di recuperare una risorsa diversa con una richiesta GET all'URI specificato nell'header Location.

POST /ordini HTTP/1.1
Host: esempio.com
Content-Type: application/json

{"prodotto": "laptop", "quantità": 1}

// Il server risponde con:
HTTP/1.1 303 See Other
Location: /ordini/789

304 Not Modified

Indica che la risorsa non è stata modificata dall'ultima richiesta, permettendo al client di utilizzare la sua copia memorizzata nella cache. Questo ottimizza il traffico di rete evitando di trasmettere contenuti non modificati.

GET /articoli/123 HTTP/1.1
Host: esempio.com
If-Modified-Since: Wed, 15 Mar 2025 12:00:00 GMT

// Il server risponde con:
HTTP/1.1 304 Not Modified
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Cache-Control: max-age=3600

307 Temporary Redirect

Simile al 302, ma specifica che il metodo di richiesta e il corpo non devono cambiare quando si effettua la richiesta reindirizzata.

308 Permanent Redirect

Simile al 301, ma specifica che il metodo di richiesta e il corpo non devono cambiare quando si effettua la richiesta reindirizzata.

Codici 4xx - Errori del client

I codici di stato 4xx indicano che la richiesta contiene una sintassi errata o non può essere soddisfatta per qualche motivo attribuibile al client. Questi errori sono generalmente risolvibili lato client.

400 Bad Request

Indica che il server non ha potuto comprendere la richiesta a causa di una sintassi non valida. Questo può verificarsi quando i parametri della richiesta sono malformati o mancanti.

POST /utenti HTTP/1.1
Host: esempio.com
Content-Type: application/json

{malformed json data}

// Il server risponde con:
HTTP/1.1 400 Bad Request
Content-Type: application/json

{"errore": "JSON non valido nella richiesta"}

401 Unauthorized

Indica che la richiesta richiede autenticazione. Il client deve fornire credenziali valide per accedere alla risorsa.

GET /area-riservata HTTP/1.1
Host: esempio.com

// Il server risponde con:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="Area riservata"

402 Payment Required

Questo codice è riservato per uso futuro. Era originariamente pensato per sistemi di pagamento digitale, ma non è ampiamente utilizzato. Alcune API lo utilizzano per indicare limiti di utilizzo gratuito superati.

403 Forbidden

Indica che il server ha compreso la richiesta, ma rifiuta di autorizzarla. A differenza del 401, l'autenticazione non risolverebbe il problema, poiché il client non ha i permessi necessari.

GET /admin/impostazioni HTTP/1.1
Host: esempio.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

// Il server risponde con:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{"errore": "Non hai i permessi per accedere a questa risorsa"}

404 Not Found

Il codice di errore più familiare per molti utenti. Indica che il server non ha trovato la risorsa richiesta. Può significare che l'URL è errato o che la risorsa non esiste più.

GET /pagina-inesistente HTTP/1.1
Host: esempio.com

// Il server risponde con:
HTTP/1.1 404 Not Found
Content-Type: text/html

<html><body><h1>Pagina non trovata</h1></body></html>

405 Method Not Allowed

Indica che il metodo HTTP utilizzato non è supportato per la risorsa richiesta. Ad esempio, tentare di utilizzare DELETE su un endpoint che supporta solo GET e POST.

DELETE /articoli HTTP/1.1
Host: esempio.com

// Il server risponde con:
HTTP/1.1 405 Method Not Allowed
Allow: GET, POST

406 Not Acceptable

Indica che il server non può produrre una risposta che soddisfi le intestazioni "Accept" inviate nella richiesta. Questo si verifica quando il client specifica formati di risposta che il server non può fornire.

407 Proxy Authentication Required

Simile al 401, ma indica che il client deve autenticarsi con un proxy.

408 Request Timeout

Indica che il server ha deciso di chiudere la connessione perché il client non ha completato la richiesta entro il tempo in cui il server era disposto ad attendere.

409 Conflict

Indica che la richiesta non può essere completata a causa di un conflitto con lo stato attuale della risorsa. Comunemente utilizzato quando si tenta di creare una risorsa che già esiste o di aggiornare una risorsa che è stata modificata da un'altra richiesta.

PUT /articoli/123 HTTP/1.1
Host: esempio.com
If-Match: "outdatedEtag"
Content-Type: application/json

{"id": 123, "titolo": "Titolo aggiornato"}

// Il server risponde con:
HTTP/1.1 409 Conflict
Content-Type: application/json

{"errore": "La risorsa è stata modificata da un altro utente"}

410 Gone

Indica che la risorsa richiesta non è più disponibile sul server e non c'è alcun indirizzo di reindirizzamento noto. A differenza del 404, questo è inteso come una condizione permanente.

411 Length Required

Indica che il server rifiuta di accettare la richiesta senza un valido header Content-Length.

412 Precondition Failed

Indica che il server non soddisfa una o più condizioni preliminari specificate dal cliente nella richiesta, come un header If-Match o If-Unmodified-Since.

413 Request Entity Too Large

Indica che la richiesta è più grande di quanto il server è disposto o in grado di elaborare, come quando si tenta di caricare un file troppo grande.

414 Request-URI Too Long

Indica che l'URI fornito era troppo lungo per essere elaborato dal server. Questo può accadere quando si utilizzano parametri query troppo complessi.

415 Unsupported Media Type

Indica che il server rifiuta di servire la richiesta perché il formato del corpo della richiesta non è supportato.

POST /articoli HTTP/1.1
Host: esempio.com
Content-Type: application/xml

<articolo><titolo>Nuovo</titolo></articolo>

// Il server risponde con:
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json

{"errore": "Formato non supportato, accettiamo solo application/json"}

416 Range Not Satisfiable

Indica che il server non può soddisfare l'intervallo richiesto nell'header Range, forse perché l'intervallo è oltre la dimensione del contenuto.

417 Expectation Failed

Indica che il server non può soddisfare i requisiti indicati nell'header Expect della richiesta.

418 I'm a teapot

Un codice di stato di risposta non standard, originariamente definito come un pesce d'aprile nell'RFC 2324, "Hyper Text Coffee Pot Control Protocol".

421 Misdirected Request

Indica che la richiesta è stata diretta a un server che non è in grado di produrre una risposta. Utilizzato in HTTP/2 quando un server riceve una richiesta con una Authority valida ma che non è configurato per gestire.

422 Unprocessable Entity

Indica che la richiesta era ben formata ma non poteva essere seguita a causa di errori semantici. Comunemente utilizzato nelle API REST per indicare errori di validazione.

POST /utenti HTTP/1.1
Host: esempio.com
Content-Type: application/json

{"nome": "Mario", "email": "non-è-un-email"}

// Il server risponde con:
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{"errori": {"email": "formato email non valido"}}

423 Locked (WebDAV)

Indica che la risorsa a cui si accede è bloccata.

424 Failed Dependency (WebDAV)

Indica che la richiesta è fallita a causa del fallimento di una richiesta precedente.

425 Too Early

Indica che il server non è disposto a rischiare l'elaborazione di una richiesta che potrebbe essere rigiocata.

426 Upgrade Required

Indica che il client dovrebbe passare a un protocollo diverso, specificato nell'header Upgrade.

428 Precondition Required

Indica che il server richiede che la richiesta sia condizionale (ad esempio, includa un header If-Match) per prevenire conflitti.

429 Too Many Requests

Indica che il client ha inviato troppe richieste in un determinato periodo di tempo. Utilizzato per il rate limiting nelle API.

GET /api/dati HTTP/1.1
Host: esempio.com

// Il server risponde con:
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{"errore": "Limite di richieste superato", "riprova_tra": 60}

431 Request Header Fields Too Large

Indica che il server non è disposto a elaborare la richiesta perché i suoi campi di intestazione sono troppo grandi.

451 Unavailable For Legal Reasons

Indica che la risorsa richiesta non è disponibile per motivi legali, come contenuti censurati per ordine del tribunale.

Codici 5xx - Errori del server

I codici di stato 5xx indicano che il server non è riuscito a soddisfare una richiesta apparentemente valida. Questi errori sono generalmente problemi lato server che devono essere risolti dagli amministratori di sistema o dagli sviluppatori.

500 Internal Server Error

Il codice di errore server più comune. Indica che si è verificato un errore imprevisto sul server che ha impedito il completamento della richiesta.

GET /articoli/123 HTTP/1.1
Host: esempio.com

// Il server risponde con:
HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{"errore": "Si è verificato un errore inaspettato"}

501 Not Implemented

Indica che il server non supporta la funzionalità richiesta per completare la richiesta. Ad esempio, un server potrebbe restituire questo codice quando riceve un metodo HTTP che non riconosce.

502 Bad Gateway

Indica che un server, mentre agiva come gateway o proxy, ha ricevuto una risposta non valida dal server upstream.

GET /servizio-esterno/dati HTTP/1.1
Host: esempio.com

// Il server risponde con:
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

{"errore": "Il servizio upstream ha restituito una risposta non valida"}

503 Service Unavailable

Indica che il server non è attualmente disponibile, tipicamente a causa di sovraccarico o manutenzione. Spesso include un header Retry-After per suggerire quando riprovare.

GET /api/dati HTTP/1.1
Host: esempio.com

// Il server risponde con:
HTTP/1.1 503 Service Unavailable
Retry-After: 300
Content-Type: application/json

{"errore": "Servizio temporaneamente non disponibile", "riprova_tra": 300}

504 Gateway Timeout

Indica che un server, mentre agiva come gateway o proxy, non ha ricevuto una risposta tempestiva dal server upstream.

505 HTTP Version Not Supported

Indica che il server non supporta la versione del protocollo HTTP utilizzata nella richiesta.

506 Variant Also Negotiates

Indica una configurazione errata del server in cui la risorsa selezionata è configurata per negoziare la rappresentazione stessa.

507 Insufficient Storage (WebDAV)

Indica che il server non è in grado di memorizzare la rappresentazione necessaria per completare la richiesta.

508 Loop Detected (WebDAV)

Indica che il server ha rilevato un ciclo infinito durante l'elaborazione della richiesta.

510 Not Extended

Richiede estensioni per completare la richiesta.

511 Network Authentication Required

Indica che il client deve autenticarsi per ottenere l'accesso alla rete.

Gestione degli errori HTTP nelle applicazioni web moderne

La corretta gestione dei codici di stato HTTP è fondamentale per creare applicazioni web robuste e user-friendly. Ecco alcune considerazioni pratiche:

Per le API REST

Usa i codici appropriati per comunicare chiaramente lo stato delle richieste
Includi dettagli significativi nei corpi delle risposte di errore
Considera l'inclusione di un codice di errore interno o di un ID di riferimento per facilitare il debug

Esempio di una risposta di errore ben strutturata:

{
  "status": 400,
  "error": "Bad Request",
  "message": "Il campo 'email' non è un indirizzo email valido",
  "timestamp": "2025-03-15T14:33:22Z",
  "path": "/api/utenti",
  "reference": "err_7f83d"
}

Per le applicazioni frontend

Interpreta i codici di stato per mostrare messaggi appropriati agli utenti
Implementa strategie di retry per errori temporanei (come 429 o 503)
Considera reindirizzamenti appropriati per errori comuni (come 401 → pagina di login)

Per i servizi di infrastruttura

Implementa health checks che monitorano i codici di stato
Configura regole di load balancing basate sui codici di risposta
Imposta monitoring e alerting per codici di errore anomali

Codici di stato HTTP nei framework moderni

Molti framework web moderni offrono modi semplificati per gestire i codici di stato HTTP. Ecco alcuni esempi rapidi:

Express (Node.js)

app.get("/risorsa/:id", (req, res) => {
  if (!req.params.id) {
    return res.status(400).json({ errore: "ID mancante" });
  }

  // Gestione 404
  if (!risorseDb[req.params.id]) {
    return res.status(404).json({ errore: "Risorsa non trovata" });
  }

  // Successo
  return res.status(200).json(risorseDb[req.params.id]);
});

Spring Boot (Java)

@GetMapping("/risorsa/{id}")
public ResponseEntity<?> getRisorsa(@PathVariable String id) {
    if (id == null) {
        return ResponseEntity.badRequest().body("ID mancante");
    }

    Optional<Risorsa> risorsa = risorsaRepository.findById(id);
    if (risorsa.isEmpty()) {
        return ResponseEntity.notFound().build();
    }

    return ResponseEntity.ok(risorsa.get());
}

Laravel (PHP)

public function show($id)
{
    if (!$id) {
        return response()->json(['errore' => 'ID mancante'], 400);
    }

    $risorsa = Risorsa::find($id);
    if (!$risorsa) {
        return response()->json(['errore' => 'Risorsa non trovata'], 404);
    }

    return response()->json($risorsa, 200);
}

Conclusione

I codici di stato HTTP sono un linguaggio universale per la comunicazione tra client e server sul web. Comprendere il loro significato e utilizzarli correttamente è fondamentale per sviluppare applicazioni web robuste, intuitive e conformi agli standard.

Una gestione accurata dei codici di stato può:

Migliorare l'esperienza utente fornendo feedback chiari sugli errori
Facilitare il debug e la manutenzione delle applicazioni
Ottimizzare le prestazioni attraverso un uso appropriato della cache
Garantire l'interoperabilità tra diversi sistemi e framework

La prossima volta che ti imbatti in un errore durante la navigazione o lo sviluppo, ricorda che quei tre semplici numeri racchiudono informazioni preziose che possono guidarti verso una soluzione.

Risorse utili

MDN Web Docs: HTTP response status codes
RFC 7231 - Specifiche HTTP/1.1: Semantics and Content
HTTP Status Dogs - Un modo divertente per memorizzare i codici di stato
HTTP Status Cats - Un'alternativa felina per ricordare i codici HTTP
httpstatuses.com - Riferimento dettagliato per tutti i codici HTTP