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.
Indice dei contenuti
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.
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.
