422 Unprocessable Entity: cosa significa e come risolverlo

Cosa significa 422 Unprocessable Entity

Il 422 ha avuto origine in WebDAV (RFC 4918) ed è stato successivamente adottato ampiamente dalle API REST come risposta standard per i fallimenti di convalida semantica. RFC 9110 ha formalmente rinominato il testo di stato in 422 Unprocessable Content, eliminando la dicitura specifica di WebDAV "Entity," anche se entrambi i nomi descrivono lo stesso identico codice di stato e "Unprocessable Entity" resta l'etichetta di gran lunga più comune nei valori predefiniti dei framework e nella documentazione delle API. La distinzione che conta è sintassi contro semantica: il JSON è stato interpretato correttamente, ogni tipo di campo richiesto corrisponde, e la richiesta è ben formata secondo ogni regola strutturale, ma un valore al suo interno viola una regola di business, come un indirizzo email nel formato sbagliato, una data nel passato dove è richiesta una data futura, o un campo che fa riferimento a un record che non esiste.

Come appare l'errore

Un 422 quasi mai compare come errore di navigazione del browser, dato che è schiacciantemente una risposta API piuttosto che qualcosa che un link o un invio di modulo innesca direttamente; compare in una scheda di rete, in un avviso toast, o in un'asserzione di test fallita. Dalla riga di comando, il corpo della risposta è dove si trova il dettaglio utile:

curl -i -X POST https://api.example.com/v1/users   -H "Content-Type: application/json"   -d '{"email": "not-an-email", "age": -5}'

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{"errors": {"email": ["is not a valid email"], "age": ["must be greater than 0"]}}

La maggior parte delle API ben costruite restituisce un corpo di errore strutturato insieme al 422, nominando esattamente quale campo è fallito e perché, invece di lasciare che chi chiama indovini dal solo codice di stato.

Cosa causa un 422 Unprocessable Entity

• Errori di convalida nelle API REST. Le applicazioni Rails comunemente restituiscono 422 automaticamente quando un modello ActiveRecord fallisce la convalida alla creazione o all'aggiornamento. La convalida delle form request di Laravel restituisce 422 per impostazione predefinita per le regole fallite. FastAPI, costruito su Pydantic, restituisce 422 ogni volta che i dati della richiesta falliscono un controllo di tipo o vincolo di un modello Pydantic, motivo per cui è uno dei codici di stato più frequentemente visti specificamente nei progetti FastAPI.
• Un campo con il tipo giusto ma un valore non valido. Una stringa dove era attesa una stringa, ma una che fallisce un controllo di formato, un limite di lunghezza, o una lista di valori permessi.
• Un riferimento a qualcosa che non esiste. Una chiave esterna, un id utente, o uno slug nel corpo della richiesta che è sintatticamente a posto ma non corrisponde ad alcun record reale.
• Regole di business oltre la semplice convalida dei campi. Un codice sconto che è sintatticamente valido ma scaduto, o una quantità che è un intero valido ma supera lo stock disponibile.
• Un campo richiesto mancante del tutto. A seconda del framework, un campo richiesto assente può restituire 422 invece di 400, dato che la richiesta si interpreta bene, semplicemente manca di un valore che il livello di convalida richiede.

422 contro 400

La linea è sintassi contro semantica. 400 Bad Request significa che il server non è riuscito a interpretare affatto la richiesta, per esempio JSON malformato o un corpo che non è valido secondo alcuna regola strutturale. 422 significa che la richiesta si è interpretata senza alcun problema, e ogni campo è del tipo giusto, ma un valore al suo interno fallisce una regola che l'applicazione controlla dopo l'interpretazione. In pratica molte API sfumano questa distinzione e usano 400 per entrambi i casi, il che è difendibile ma meno preciso; un client che si integra con un'API dovrebbe leggere il corpo della risposta invece di affidarsi solo al codice di stato per sapere esattamente cosa è fallito.

Come correggere un errore 422

Se sei un client che chiama un'API

1. Leggi il corpo della risposta, non solo il codice di stato. La risposta 422 di un'API ben costruita nomina il campo e la regola specifici che sono falliti, il che ti dice esattamente cosa correggere senza ulteriori congetture.
2. Controlla il campo contro i vincoli documentati dell'API come formato, lunghezza, e valori permessi, dato che queste sono regole di business che il solo schema non ti mostrerà.
3. Tratta il 422 come un segnale per correggere i dati, non per riprovare la richiesta invariata. Riprovare una richiesta non modificata che ha fallito la convalida fallirà in modo identico ogni volta; un client ben progettato dovrebbe mostrare l'errore specifico all'utente invece di riprovare silenziosamente.

Se gestisci l'API

1. Restituisci sempre un corpo di errore strutturato insieme al 422, nominando il campo e la regola che sono falliti, invece di un semplice codice di stato senza spiegazione.
2. Mantieni i messaggi di errore di convalida specifici e attuabili, per esempio "email must be a valid address" invece di un generico "validation failed" che costringe chi chiama a indovinare quale tra diversi campi fosse il problema.
3. Decidi deliberatamente tra 400 e 422 per la tua API e documenta la scelta, così chi integra può costruire una gestione degli errori affidabile invece di trattare ogni 4xx allo stesso modo.
4. Registra i payload convalidati-ma-rifiutati durante lo sviluppo per cogliere i casi in cui il tuo stesso codice client sta inviando dati che falliscono costantemente la convalida, il che spesso indica un mismatch tra il client e le regole effettive dell'API.

Come un client dovrebbe gestire una risposta 422

Un client ben progettato tratta il 422 come fondamentalmente diverso da un errore 5xx o un fallimento di rete: significa che il server è in buono stato e funziona correttamente, e chi chiama ha inviato qualcosa che il server non accetterà mai così com'è. La risposta giusta è interpretare il corpo dell'errore, mappare ogni campo fallito indietro al modulo o all'input che lo ha prodotto, e mostrare all'utente qualcosa di attuabile, non riprovare con un backoff come faresti per un timeout o un 503. I test automatizzati che esercitano il livello di convalida di un'API dovrebbero asserire sul corpo di errore specifico restituito, non solo sul codice di stato 422, dato che è quello a confermare che la logica di convalida stessa sia corretta.

Come prevenire che i 422 passino inosservati

Una regola di convalida che è cambiata inaspettatamente, sia da un deploy, un aggiornamento di una libreria di terze parti, o una migrazione di schema, può iniziare silenziosamente a rifiutare richieste che prima riuscivano. Un controllo HTTP che invia un payload noto come valido e asserisce sul codice di stato atteso coglie quel tipo di regressione immediatamente dopo un deploy. Per API con più di un endpoint o un payload che il solo codice di stato non può verificare completamente, il monitoraggio API che controlla anche il corpo della risposta conferma la logica di convalida stessa, non solo che il server sia raggiungibile.

Errori correlati

Vedi 400 Bad Request per il caso di richiesta-non-interpretabile contro cui questa guida fa da contrasto, la panoramica 4xx per la famiglia più ampia, e 401 Unauthorized e 405 Method Not Allowed altrove in questo lotto.

Domande frequenti

422 Unprocessable Entity è la stessa cosa di 422 Unprocessable Content?

Sì. RFC 9110 ha rinominato la frase motivo in Unprocessable Content, ma è lo stesso codice di stato con lo stesso significato; la maggior parte dei framework e delle documentazioni API usa ancora la dicitura più vecchia Unprocessable Entity.

Perché la mia app FastAPI restituisce 422 per un campo mancante?

FastAPI convalida automaticamente i dati della richiesta contro i tuoi modelli Pydantic, e un campo richiesto mancante, o uno con il tipo sbagliato, fallisce quella convalida e restituisce 422 con un corpo che descrive esattamente quale campo e regola sono falliti.

Dovrei riprovare una richiesta che ha ricevuto un 422?

Solo dopo aver cambiato i dati che hanno fallito la convalida. Riprovare la richiesta identica produrrà il 422 identico ogni volta, dato che il server sta correttamente e coerentemente rifiutando lo stesso input non valido.

Qual è la differenza tra 422 e 400 in pratica?

400 è per una richiesta che il server non riesce affatto a interpretare. 422 è per una richiesta che si interpreta bene ma contiene un valore che fallisce una regola di convalida o di business. Molte API nel mondo reale usano 400 per entrambi, quindi controlla sempre la convenzione documentata per la specifica API che stai chiamando.

Un 422 può significare che il server ha un bug?

Può succedere, se la regola di convalida stessa è sbagliata, per esempio rifiutando un formato email genuinamente valido. Ma un 422 per progettazione significa che il server sta funzionando come previsto e sta obiettando ai dati, quindi indaga la regola di convalida effettiva prima di assumere che sia rotta.