I codici di stato HTTP o Status Codes, sono i codici a tre cifre che indicano l’esito di una comunicazione tra client e server che usano il protocollo HTTP o HTTPS, come i browser web e le API.
Questi codici, che generalmente restano nascosti all’utilizzatore del servizio, permettono al client di conoscere l’esito della sua richiesta ancora prima di analizzare il payload, che è la risposta vera e propria.
Tra gli HTTP Codes più comuni ci sono l’HTTP Status 404, che compare quando si cerca di collegarsi a una pagina web che non esiste, e l’HTTP Status 500, che indica un errore del server. Anche le richieste che vanno a buon fine, però, hanno i loro codici: vediamo quali sono e cosa indicano.
HTTP Status Codes nelle API REST
Il protocollo HTTP è un metodo di trasporto delle informazioni largamente utilizzato nelle architetture client-server, che ha trovato perfetta applicazione anche nell’ambito delle chiamate API REST.
Nelle chiamate API succede esattamente quello che succede quando, navigando in internet, un client HTTP chiede una risorsa a un server: quando il client API fa la sua richiesta, il server risponde inviando l’HTTP Status Code che indica il tipo di risposta. Quello che cambia è il contenuto della risposta, o payload, che invece di contenere una pagina HTML contiene un json.
I Codici HTTP sono identici per tutti gli applicativi che comunicano tramite questo protocollo, e costituiscono parte della risposta di un server HTTP.
Come è fatta una risposta API REST?
Quando un client API interroga un server, riceve indietro una risposta che contiene diverse informazioni e che, al netto di specifiche tecniche, include alcune sezioni fondamentali:
- Codici di stato HTTP: sono composti di tre cifre. Indicano l’esito della comunicazione e danno informazioni al client su come procedere;
- Header: contiene gli attributi di intestazione, che riguardano generalmente il formato del corpo della richiesta, i tempi di conservazione in cache della risposta e soprattutto le autorizzazioni di cui il client dispone;
- Payload: è il contenuto vero e proprio della risposta API, quello che contiene i dati.
Gli HTTP Status Codes sono parte integrante di una risposta API: la loro trasmissione permette al client di sapere cosa è successo durante il trasferimento ancora prima di analizzare il contenuto della risposta. Un HTTP Status 403, per esempio, indica che il client è autenticato ma non può accedere alla risorsa richiesta. Uno Status Code 200, invece, significa che la richiesta è andata a buon fine e che il server ha restituito i dati richiesti.
Codici di stato HTTP: quali sono
I codici di stato HTTP sono divisi in cinque classi, ciascuna delle quali inizia con una cifra che indica il tipo di risposta:
- 1xx – Messaggio informativo: questo tipo di risposta indica che il server ha ricevuto la richiesta e la sta elaborando;
- 2xx – Messaggio di successo: la richiesta è stata ricevuta, compresa ed elaborata correttamente dal server;
- 3xx – Risposta di reindirizzamento: comunicano al client che deve eseguire delle azioni aggiuntive per soddisfare la richiesta (per esempio quando una risorsa viene trasferita, l’HTTP Status 301 chiede di puntare verso la nuova Url);
- 4xx – Messaggio di errore del client: compare per esempio quando le credenziali non sono valide o la richiesta è stata digitata male;
- 5xx – Risposta di errore del server: indica che il server non ha soddisfatto la richiesta perché ha riscontrato un errore o non riesce a gestire la richiesta.
| Codice | Nome | Significato |
|---|---|---|
| 1xx – Risposte informative | ||
| 100 | Continue | Il client può continuare a inviare la richiesta. |
| 101 | Switching Protocols | Il server accetta di cambiare il protocollo utilizzato. |
| 102 | Processing | Il server ha ricevuto la richiesta e la sta elaborando. |
| 103 | Early Hints | Fornisce indicazioni preliminari prima della risposta definitiva. |
| 104 | Upload Resumption Supported | Indica il supporto temporaneo alla ripresa di un caricamento interrotto. |
| 2xx – Richiesta completata con successo | ||
| 200 | OK | La richiesta è stata completata correttamente. |
| 201 | Created | La richiesta ha creato una nuova risorsa. |
| 202 | Accepted | La richiesta è stata accettata, ma non ancora completata. |
| 203 | Non-Authoritative Information | Le informazioni provengono da una fonte diversa dal server originario. |
| 204 | No Content | La richiesta è riuscita, ma non viene restituito alcun contenuto. |
| 205 | Reset Content | Il client deve reimpostare la vista o il modulo utilizzato. |
| 206 | Partial Content | Il server restituisce soltanto una parte della risorsa richiesta. |
| 207 | Multi-Status | La risposta contiene lo stato di più operazioni WebDAV. |
| 208 | Already Reported | La risorsa WebDAV è già stata inclusa nella risposta. |
| 226 | IM Used | La risposta rappresenta il risultato di una o più trasformazioni. |
| 3xx – Reindirizzamenti | ||
| 300 | Multiple Choices | Sono disponibili più rappresentazioni o destinazioni della risorsa. |
| 301 | Moved Permanently | La risorsa è stata spostata definitivamente a un nuovo URL. |
| 302 | Found | La risorsa si trova temporaneamente presso un altro URL. |
| 303 | See Other | La risposta deve essere recuperata da un altro URL tramite GET. |
| 304 | Not Modified | La risorsa non è cambiata e può essere utilizzata dalla cache. |
| 305 | Use Proxy | Codice deprecato: richiedeva l’utilizzo di un proxy. |
| 306 | Unused | Codice non più utilizzato e riservato. |
| 307 | Temporary Redirect | Reindirizzamento temporaneo che mantiene metodo e corpo della richiesta. |
| 308 | Permanent Redirect | Reindirizzamento permanente che mantiene metodo e corpo della richiesta. |
| 4xx – Errori del client | ||
| 400 | Bad Request | La richiesta è errata, incompleta o non comprensibile. |
| 401 | Unauthorized | È necessaria un’autenticazione valida per accedere alla risorsa. |
| 402 | Payment Required | Codice riservato per sistemi che richiedono un pagamento. |
| 403 | Forbidden | Il server ha compreso la richiesta, ma rifiuta l’accesso. |
| 404 | Not Found | La risorsa richiesta non è stata trovata. |
| 405 | Method Not Allowed | Il metodo HTTP utilizzato non è consentito per la risorsa. |
| 406 | Not Acceptable | Il server non può produrre una risposta nel formato richiesto. |
| 407 | Proxy Authentication Required | È necessario autenticarsi presso il proxy. |
| 408 | Request Timeout | Il server ha atteso troppo a lungo il completamento della richiesta. |
| 409 | Conflict | La richiesta è in conflitto con lo stato attuale della risorsa. |
| 410 | Gone | La risorsa è stata rimossa definitivamente. |
| 411 | Length Required | È necessario specificare la lunghezza del contenuto. |
| 412 | Precondition Failed | Una condizione indicata nella richiesta non è stata soddisfatta. |
| 413 | Content Too Large | Il contenuto inviato supera il limite accettato dal server. |
| 414 | URI Too Long | L’indirizzo della richiesta è troppo lungo. |
| 415 | Unsupported Media Type | Il formato del contenuto inviato non è supportato. |
| 416 | Range Not Satisfiable | L’intervallo di byte richiesto non può essere restituito. |
| 417 | Expectation Failed | Il server non può soddisfare le aspettative indicate nella richiesta. |
| 418 | Unused | Codice non utilizzato, storicamente noto come “I’m a teapot”. |
| 421 | Misdirected Request | La richiesta è stata inviata a un server non in grado di rispondere. |
| 422 | Unprocessable Content | La richiesta è corretta, ma il contenuto non può essere elaborato. |
| 423 | Locked | La risorsa richiesta è bloccata. |
| 424 | Failed Dependency | L’operazione non è riuscita a causa del fallimento di una dipendenza. |
| 425 | Too Early | Il server rifiuta una richiesta che potrebbe essere ripetuta prematuramente. |
| 426 | Upgrade Required | Il client deve passare a un protocollo differente. |
| 428 | Precondition Required | Il server richiede che la richiesta sia condizionale. |
| 429 | Too Many Requests | Il client ha inviato troppe richieste in un determinato periodo. |
| 431 | Request Header Fields Too Large | Le intestazioni della richiesta sono troppo grandi. |
| 451 | Unavailable For Legal Reasons | La risorsa non è disponibile per motivi legali. |
| 5xx – Errori del server | ||
| 500 | Internal Server Error | Il server ha incontrato un errore interno imprevisto. |
| 501 | Not Implemented | Il server non supporta la funzionalità richiesta. |
| 502 | Bad Gateway | Il gateway ha ricevuto una risposta non valida dal server a monte. |
| 503 | Service Unavailable | Il servizio è temporaneamente indisponibile. |
| 504 | Gateway Timeout | Il gateway non ha ricevuto una risposta entro il tempo previsto. |
| 505 | HTTP Version Not Supported | La versione HTTP utilizzata non è supportata dal server. |
| 506 | Variant Also Negotiates | Si è verificato un errore nella negoziazione del contenuto. |
| 507 | Insufficient Storage | Il server non dispone dello spazio necessario per completare la richiesta. |
| 508 | Loop Detected | Il server ha rilevato un ciclo infinito durante l’elaborazione. |
| 510 | Not Extended | Codice obsoleto: erano necessarie ulteriori estensioni. |
| 511 | Network Authentication Required | È necessario autenticarsi sulla rete, ad esempio tramite un captive portal. |
Ogni tipologia di risposta, a sua volta, include diversi possibili messaggi. Ecco i più comuni.
Response Code HTTP 1xx: Messaggio informativo
I messaggi informativi vengono trasmessi quando la richiesta è stata ricevuta dal server e che sta proseguendo con l’elaborazione della request: spesso vengono usati per evitare che il client vada in time-out mentre aspetta la risposta, ma possono indicare anche che è necessario inviare ulteriori informazioni per completare la richiesta.
- 100 – Continua: la parte iniziale della richiesta è stata ricevuta e il server chiede di inviare il resto (per esempio: ha ricevuto l’Header con le credenziali e chiede che gli venga inviato il Payload);
- 101 – Cambio di protocollo: il client ha chiesto di cambiare il protocollo in uso e il server comunica il cambio di protocollo nella connessione;
- 102 – Elaborazione: indica che il server sta ancora elaborando la richiesta.
Codici HTTP 2xx: Successo
I messaggi di successo indicano che la richiesta è stata ricevuta ed elaborata con successo. Questo non significa necessariamente che il client avrà quello che voleva: la risposta del server infatti potrebbe anche essere priva di contenuto.
- 200 – OK: indica che la richiesta è andata a buon fine e che il server ha restituito i dati richiesti;
- 201 – Created: significa che la richiesta ha avuto successo e il server ha creato una nuova risorsa;
- 204 – No content: la richiesta ha avuto successo ma non ci sono dati da trasferire.
HTTP Codes 3xx: Risposte di reindirizzamento
I codici HTTP che iniziano con 3 indicano che il client deve eseguire ulteriori azioni per soddisfare la richiesta: vengono utilizzati, per esempio, quando la risorsa ricercata è stata spostata in una posizione diversa.
- 301 – Moved Permanently: la risorsa è stata spostata a una nuova Url, quindi il client deve aggiornare i link e puntare al nuovo indirizzo;
- 303 – See Other (Vedi altro): indica che la risposta è disponibile a un indirizzo diverso, quindi il client deve eseguire una richiesta GET a quella Url per recuperarla.
HTTP error codes: i codici 4xx
I codici di errore che iniziano con il numero 4 sono forse i più temuti dagli utilizzatori di client API, in quanto indicano che la richiesta non può essere soddisfatta a causa di un errore del client, che potrebbe aver sbagliato la sintassi o non disporre delle autorizzazioni necessarie. Gli Status Code HTTP 400 più comuni sono:
- Errore 400 – Bad request: la richiesta non è valida o non è scritta nella maniera corretta;
- Errore 401 – Non autorizzato: il client non possiede l’autorizzazione per accedere alla risorsa;
- Errore 403 – Forbidden: il client è autenticato ma non autorizzato ad accedere alla richiesta;
- Errore 404 – Not Found: la risorsa richiesta non è stata trovata sul server:
- Errore 408 – Request Timeout: il tempo per inviare la richiesta è scaduto e il server ha terminato la connessione;
- Errore 429 – Too many requests: significa che il client ha effettuato troppe richieste in un breve intervallo di tempo, laddove esistano dei limiti alle chiamate.
I messaggi di errore 500: gli errori del server
I messaggi di errore non riguardano solo il client: esistono anche degli errori interni al server, che vengono indicati con un codice di tre cifre che inizia con 5. I più comuni sono:
- 500 – Errore interno del server: è un codice generico che indica un errore del server che gli ha impedito di soddisfare la richiesta;
- 502 – Bad Gateway: un server con funzione di gateway o proxy ha ricevuto una risposta non valida da un server di upstream, quello a monte;
- 503 – Servizio non disponibile: significa che il server non è temporaneamente in grado di gestire la richiesta, per esempio perché è in fase di manutenzione o c’è un picco nel traffico.
