Codici HTTP e risposte API

In parole semplici

Quando il browser parla con un server, ogni risposta arriva accompagnata da un codice di stato HTTP: tre cifre con un significato preciso. Saperli leggere ti dice in tre secondi dove vive il problema: nel client, nei permessi, nei dati, nel server o nel gateway.

Senza questa lettura, ogni “errore di rete” sembra uguale agli altri.

Parole nuove

• status code: codice numerico (100–599) che classifica la risposta HTTP.
• client error (4xx): il problema è nella richiesta (cosa hai chiesto, come l’hai chiesto, chi sei).
• server error (5xx): il problema è dal lato server.
• gateway: server intermedio (reverse proxy, CDN, load balancer).
• rate limit: numero massimo di richieste consentite in un certo intervallo.

Cosa impari

• Leggere le classi di codici e i singoli codici frequenti.
• Distinguere errore client da errore server in un secondo.
• Usare curl o httpie per replicare una richiesta fuori dal browser.

Le cinque classi

Classe	Significato	Esempio
1xx	informativo (raro)	100 Continue, 101 Switching Protocols
2xx	successo	200 OK, 201 Created, 204 No Content
3xx	redirect	301 Permanent, 302 Found, 304 Not Modified
4xx	errore client	400, 401, 403, 404, 409, 422, 429
5xx	errore server	500, 502, 503, 504

Regola di base: 4xx = colpa del client, 5xx = colpa del server. Non sempre vero alla lettera, ma ottima approssimazione iniziale.

I codici 4xx più frequenti

400 Bad Request

La richiesta è malformata. Body invalido, JSON rotto, header mancante.

Domanda: che cosa mando di preciso? curl -v o pannello Network mostrano il body inviato.

401 Unauthorized

Non sei autenticato (o il token è scaduto/invalido). Attenzione: il nome è fuorviante; significa “non identificato”, non “non autorizzato”.

Domanda: c’è l’header Authorization? Il token è ancora valido?

403 Forbidden

Sei identificato ma non hai i permessi per questa operazione.

Domanda: il ruolo dell’utente può fare questo? Lato server, qual è la regola che lo blocca?

404 Not Found

La risorsa non esiste a quell’URL. Spesso è un URL sbagliato (typo, slash di troppo, versione API errata).

Domanda: l’URL è esattamente quello documentato? Maiuscole/minuscole?

409 Conflict

La richiesta confligge con lo stato attuale (es. provare a creare una risorsa con un id già esistente, o aggiornare una versione obsoleta).

Domanda: c’è già una risorsa con quei dati? La versione che invio è ancora attuale?

422 Unprocessable Entity

Il body è sintatticamente valido ma semanticamente sbagliato (campi mancanti, valori fuori dominio).

Domanda: quali validazioni ha il server? Solitamente la risposta include il dettaglio.

429 Too Many Requests

Hai superato il rate limit.

Domanda: quante richieste al secondo sto facendo? L’header Retry-After dice quanto attendere.

I codici 5xx più frequenti

500 Internal Server Error

Errore generico lato server. Spesso un’eccezione non gestita.

Domanda: cosa dicono i log del server in quel timestamp?

502 Bad Gateway

Il gateway (reverse proxy, CDN, load balancer) ha ricevuto risposta invalida dal server di backend.

Domanda: il backend è acceso? Sta crashando?

503 Service Unavailable

Il server è temporaneamente non disponibile (sovraccarico, deploy in corso).

Domanda: c’è un’operazione di manutenzione? Il sistema è in fase di scaling?

504 Gateway Timeout

Il gateway ha aspettato troppo la risposta del backend.

Domanda: la richiesta richiede un’operazione lenta? Va spezzata o messa in coda?

Tabella di lettura rapida

Codice	Lettura in una frase	Primo passo
400	”non capisco cosa mi mandi”	leggi body inviato vs schema
401	”chi sei?“	controlla token
403	”so chi sei, ma non puoi”	controlla ruolo/permessi
404	”qui non c’è niente”	controlla URL/metodo
409	”stato attuale incompatibile”	leggi lo stato lato server
422	”campo X non valido”	leggi messaggio di validazione
429	”troppe richieste”	leggi Retry-After
500	”ho un bug”	log del server
502	”il backend dietro di me non risponde bene”	salute backend
503	”non disponibile ora”	stato deploy/scaling
504	”il backend è troppo lento”	timeout, operazione lunga

Riprodurre la richiesta da terminale

DevTools mostra ciò che il browser fa. Per isolare il bug è utile replicare la richiesta fuori dal browser, dove non ci sono estensioni, cookie auto, cache, redirect.

curl

curl -v -X POST https://api.esempio.it/utenti \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxx" \
  -d '{"nome":"Carlo"}'

L’opzione -v mostra header inviati e ricevuti. Indispensabile.

httpie (più leggibile)

http POST https://api.esempio.it/utenti \
  Authorization:"Bearer xxx" \
  nome=Carlo

Se la richiesta funziona da terminale ma non dal browser, il bug vive nel browser (CORS, cache, cookie, estensione). Se fallisce in entrambi, è server o richiesta.

Esercizio guidato

1. Apri DevTools → Network.
2. Naviga in un’app che usi (anche un sito normale).
3. Trova una risposta 4xx e una 5xx (anche su asset secondari).
4. Per ognuna scrivi: URL, codice, interpretazione in una frase, prossimo passo.
5. Replica la richiesta 4xx con curl -v. Confronta header e body con quelli del browser.

Errori frequenti del principiante

• Trattare tutti gli errori HTTP come “non funziona la rete”. Il codice è già una diagnosi.
• Confondere 401 e 403. Uno è “non so chi sei”, l’altro è “so chi sei ma non puoi”.
• Ignorare il body della risposta 4xx. Spesso contiene il dettaglio del campo sbagliato.
• Re-tentare a tappeto un 5xx. Aggrava il problema. Aspetta Retry-After, usa backoff esponenziale (modulo 8).