REST API Status Codes: quali sono e come funzionano

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, come i browser web e le applicazioni 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.

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.

 

Accedi a dati affidabili e di alta qualità!

Scopri gli oltre 400 services

del Marketplace Openapi.com

SCOPRI ORA