Errore 422 Unprocessable Content: validazione API

In breve: Errore 422 Unprocessable Content: validazione API: L’errore 422 Unprocessable Content indica che il server comprende il tipo e la sintassi della richiesta, ma non può elaborare le istruzioni contenute.

Errore 422 Unprocessable Content: validazione API

Questa guida approfondisce errore 422 Unprocessable Content con verifiche progressive e reversibili. Non inviare password, cookie, token, chiavi private, codici 2FA o file di configurazione completi nei ticket.

Che cosa significa

Un JSON può essere formalmente valido e ricevere comunque 422 perché manca un campo obbligatorio, un valore ha il tipo sbagliato o lo stato della risorsa non consente l’operazione.

Il corpo della risposta è spesso più importante del codice: può contenere il nome del campo, il vincolo e un identificativo utile per correggere la richiesta.

Come riconoscere il problema

• L’API restituisce errori di validazione per campo.
• Il medesimo endpoint accetta un payload più semplice.
• Un ordine o utente non può essere creato per dati duplicati.
• Il nonce è presente ma non valido per l’azione.
• La sintassi JSON supera il parser ma la logica rifiuta i valori.

Cause più frequenti

1. Campo obbligatorio mancante

Lo schema richiede un valore non fornito. Confronta questa ipotesi con il messaggio completo e con i log dell’orario interessato, evitando conclusioni basate soltanto sulla schermata mostrata dal client.

2. Tipo o formato errato

Data, email, numero o enumerazione non rispettano il contratto.

3. Vincolo di unicità

Slug, username o identificativo esistono già.

4. Regola business

Lo stato della risorsa non consente la transizione.

5. Nonce o token applicativo

L’autorizzazione è formalmente presente ma non valida per il contesto.

6. Versione API differente

Il client usa campi di una release non compatibile.

Diagnosi passo per passo

1. Leggi tutti gli errori nel corpo. Non fermarti al primo campo. Salva il risultato prima di passare al controllo successivo, così potrai individuare il punto preciso nel quale il comportamento cambia.
2. Confronta con lo schema ufficiale. Verifica nomi, tipi e valori ammessi. Salva il risultato prima di passare al controllo successivo, così potrai individuare il punto preciso nel quale il comportamento cambia.
3. Riduci il payload. Parti dai soli campi obbligatori. Salva il risultato prima di passare al controllo successivo, così potrai individuare il punto preciso nel quale il comportamento cambia.
4. Controlla dati duplicati. Cerca la risorsa esistente. Salva il risultato prima di passare al controllo successivo, così potrai individuare il punto preciso nel quale il comportamento cambia.
5. Verifica stato e transizioni. Conferma che l’operazione sia consentita. Salva il risultato prima di passare al controllo successivo, così potrai individuare il punto preciso nel quale il comportamento cambia.
6. Controlla versione e endpoint. Evita esempi riferiti a release differenti. Salva il risultato prima di passare al controllo successivo, così potrai individuare il punto preciso nel quale il comportamento cambia.
7. Registra request ID e orario. Correla la richiesta con il log applicativo. Salva il risultato prima di passare al controllo successivo, così potrai individuare il punto preciso nel quale il comportamento cambia.

Procedura di risoluzione

1. Correggi campi e tipi. Invia valori nel formato documentato. Dopo la modifica ripeti il test originale e verifica che non siano comparsi nuovi errori o regressioni.
2. Aggiungi dati obbligatori. Senza includere informazioni non richieste. Dopo la modifica ripeti il test originale e verifica che non siano comparsi nuovi errori o regressioni.
3. Aggiorna la risorsa esistente. Quando il conflitto deriva da un duplicato. Dopo la modifica ripeti il test originale e verifica che non siano comparsi nuovi errori o regressioni.
4. Esegui la transizione corretta. Segui l’ordine previsto dall’applicazione. Dopo la modifica ripeti il test originale e verifica che non siano comparsi nuovi errori o regressioni.
5. Rigenera nonce o token. Usa una sessione valida e permessi adeguati. Dopo la modifica ripeti il test originale e verifica che non siano comparsi nuovi errori o regressioni.
6. Aggiorna il client. Allinea schema e versione API. Dopo la modifica ripeti il test originale e verifica che non siano comparsi nuovi errori o regressioni.
7. Gestisci gli errori nel software. Mostra al chiamante il campo da correggere senza retry automatici infiniti. Dopo la modifica ripeti il test originale e verifica che non siano comparsi nuovi errori o regressioni.

Domande frequenti

Guide Xlogic correlate

• Errore 409 Conflict: API, salvataggi e risorse
• Errore 413 Content Too Large: cause e soluzioni
• Errore 406 Not Acceptable: WAF e contenuti

Fonti tecniche

• MDN: 422 Unprocessable Content