L’errore 422 Unprocessable Content indica che il server comprende il tipo e la sintassi della richiesta, ma non può elaborare le istruzioni contenute. È frequente nelle API quando i dati violano uno schema, un vincolo o una regola applicativa.
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. Confronta questa ipotesi con il messaggio completo e con i log dell’orario interessato, evitando conclusioni basate soltanto sulla schermata mostrata dal client.
3. Vincolo di unicità
Slug, username o identificativo esistono già. Confronta questa ipotesi con il messaggio completo e con i log dell’orario interessato, evitando conclusioni basate soltanto sulla schermata mostrata dal client.
4. Regola business
Lo stato della risorsa non consente la transizione. Confronta questa ipotesi con il messaggio completo e con i log dell’orario interessato, evitando conclusioni basate soltanto sulla schermata mostrata dal client.
5. Nonce o token applicativo
L’autorizzazione è formalmente presente ma non valida per il contesto. Confronta questa ipotesi con il messaggio completo e con i log dell’orario interessato, evitando conclusioni basate soltanto sulla schermata mostrata dal client.
6. Versione API differente
Il client usa campi di una release non compatibile. Confronta questa ipotesi con il messaggio completo e con i log dell’orario interessato, evitando conclusioni basate soltanto sulla schermata mostrata dal client.
Diagnosi passo per passo
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
Metodo sicuro di diagnosi
Prima di modificare la configurazione, registra URL o servizio coinvolto, messaggio completo, data e ora, ultima modifica nota, client o rete e risultato ottenuto con un secondo strumento. Questa fotografia iniziale permette di confrontare i test e di tornare alla configurazione precedente quando una modifica non produce il risultato atteso.
Applica una sola correzione alla volta. Dopo ogni intervento ripeti esattamente la stessa operazione e controlla i log dello stesso intervallo temporale. Modificare contemporaneamente DNS, cache, PHP, plugin, proxy e firewall elimina la possibilità di attribuire il risultato a una causa precisa.
Controllo incrociato
Usa almeno due fonti indipendenti. Per HTTP confronta browser, curl e log; per WordPress confronta frontend, wp-admin, Site Health e WP-CLI; per DNS interroga nameserver autoritativi e resolver pubblici; per la posta confronta Webmail, intestazioni originali e Track Delivery. Cache, TTL e code possono mostrare stati differenti per alcuni minuti.
Quando il problema sembra risolto, esegui una seconda prova con una nuova sessione, un secondo utente o una seconda rete quando applicabile. Verifica inoltre che TLS, autenticazione, WAF, permessi e controlli antispam restino attivi: una correzione che disabilita stabilmente le protezioni non è una soluzione definitiva.
Verifica prolungata dopo la correzione
Conserva temporaneamente backup, valori precedenti ed estratti dei log. Ripeti il controllo dopo il normale ciclo di cache, cron, coda o TTL. Se l’anomalia ricompare a intervalli regolari, confronta l’orario con backup, aggiornamenti, rinnovi SSL, rotazioni DNS, processi pianificati e servizi esterni.
Documenta il risultato finale con data, comando o schermata utilizzata e condizione verificata. Questa nota evita interventi duplicati e rende più rapida una futura analisi da parte dell’assistenza.
Procedura di risoluzione
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
Come raccogliere prove utili
Quando riproduci il problema, conserva soltanto i dati tecnici necessari: codice di risposta, URL priva di token, orario con fuso, request ID, nome del client, dimensione del file o del messaggio e una breve descrizione dell’operazione. Evita screenshot parziali quando puoi esportare il testo originale, perché header, log e messaggi completi permettono una diagnosi più precisa.
Prima di chiudere il controllo, confronta il comportamento con una configurazione nota e funzionante. Per una API usa un payload minimo; per WordPress prova una funzione core senza plugin aggiuntivi; per DNS interroga direttamente i nameserver; per la posta usa Webmail e conserva il file `.eml`. Questo confronto riduce le ipotesi e impedisce modifiche inutili.
Controlli finali
- Il payload supera la validazione.
- La risorsa viene creata o aggiornata una sola volta.
- I tipi rispettano lo schema.
- Gli errori vengono gestiti chiaramente.
- Nessun dato sensibile viene registrato.
Prevenzione
- Validazione client e server.
- Schema versionato.
- Test di contratto.
- Idempotenza.
- Messaggi di errore utili.
Errori da evitare
- Non ritentare lo stesso payload in loop.
- Non ignorare il corpo risposta.
- Non convertire tutti i valori in stringhe.
- Non disabilitare la validazione.
- Non esporre dettagli sensibili negli errori.
Quando contattare l’assistenza Xlogic
Apri un ticket quando il problema persiste dopo i controlli di base, coinvolge più servizi oppure richiede log e configurazioni non disponibili nel pannello. Indica:
- endpoint e metodo
- codice e corpo risposta
- request ID
- payload minimo oscurato
- versione API
Non inviare credenziali. URL, orari, codici, header non sensibili e messaggi di errore sono sufficienti per iniziare la diagnosi.
Fonti tecniche ufficiali
Domande frequenti su errore 422 Unprocessable Content
Qual è la differenza tra 400 e 422?
Il 400 indica una richiesta non valida in generale; il 422 dati comprensibili ma non elaborabili.
Ritentare risolve?
Solo dopo aver corretto dati o stato.
Un campo duplicato può causare 422?
Sì, se viola un vincolo applicativo.
WordPress REST può usarlo?
Plugin e API personalizzate possono restituirlo per validazione.
Quale parte della risposta è più utile?
Il corpo con campo, codice applicativo e dettaglio della validazione.