422 Unprocessable Entity: co to znamená a jak to opravit

Co znamená 422 Unprocessable Entity

422 vzniklo ve WebDAV (RFC 4918) a později ho široce přijaly REST API jako standardní odpověď pro selhání sémantické validace. RFC 9110 formálně přejmenovalo text stavu na 422 Unprocessable Content a zrušilo znění "Entity" specifické pro WebDAV, i když oba názvy popisují identický stavový kód a "Unprocessable Entity" zůstává mnohem běžnějším označením ve výchozích nastaveních frameworků a dokumentaci API. Rozdíl, na kterém záleží, je syntaxe versus sémantika: JSON se zpracoval správně, každý typ povinného pole odpovídá, a požadavek je podle každého strukturálního pravidla dobře formovaný, ale hodnota uvnitř porušuje obchodní pravidlo, jako e-mailová adresa ve špatném formátu, datum v minulosti tam, kde je vyžadované budoucí datum, nebo pole odkazující na záznam, který neexistuje.

Jak se chyba projevuje

422 se skoro nikdy neobjeví jako chyba navigace v prohlížeči, protože je to naprosto převážně odpověď API, ne něco, co přímo spustí odkaz nebo odeslání formuláře; objevuje se na kartě sítě, v chybové bublině, nebo u selhaného tvrzení testu. Z příkazové řádky je tělo odpovědi tím místem, kde žije užitečný detail:

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"]}}

Většina dobře postavených API vrátí spolu s 422 strukturované tělo chyby, které přesně pojmenuje, které pole selhalo a proč, místo aby nechalo volajícího hádat jen ze stavového kódu.

Co způsobuje 422 Unprocessable Entity

• Chyby validace v REST API. Aplikace Rails běžně vrací 422 automaticky, když model ActiveRecord selže při validaci na create nebo update. Validace form request v Laravel ve výchozím stavu vrací 422 pro selhaná pravidla. FastAPI, postavené na Pydantic, vrací 422 kdykoli data požadavku selžou při kontrole typu nebo omezení modelu Pydantic, což je důvod, proč je to konkrétně v projektech FastAPI jeden z nejčastěji vídaných stavových kódů.
• Pole se správným typem, ale neplatnou hodnotou. Řetězec tam, kde byl řetězec očekávaný, ale takový, který selže při kontrole formátu, limitu délky, nebo seznamu povolených hodnot.
• Odkaz na něco, co neexistuje. Cizí klíč, id uživatele, nebo slug v těle požadavku, který je syntakticky v pořádku, ale neodpovídá žádnému skutečnému záznamu.
• Obchodní pravidla nad rámec jednoduché validace pole. Slevový kód, který je syntakticky platný, ale vypršel, nebo množství, které je platné celé číslo, ale přesahuje dostupné zásoby.
• Úplně chybějící povinné pole. Podle frameworku může chybějící povinné pole vrátit 422 místo 400, protože se požadavek v pořádku zpracuje, jen mu chybí hodnota, kterou validační vrstva vyžaduje.

422 versus 400

Hranice je syntaxe versus sémantika. 400 Bad Request znamená, že server požadavek vůbec nedokázal zpracovat, například poškozený JSON nebo tělo, které není platné podle žádného strukturálního pravidla. 422 znamená, že se požadavek zpracoval bez problémů a každé pole má správný typ, ale hodnota uvnitř selže na pravidle, které aplikace kontroluje po zpracování. V praxi hodně API tenhle rozdíl stírá a používá 400 pro oba případy, což je obhajitelné, ale méně přesné; klient integrující se s API by měl přečíst tělo odpovědi, místo aby se pro přesné zjištění, co selhalo, spoléhal jen na stavový kód.

Jak opravit chybu 422

Pokud jste klient volající API

1. Přečtěte si tělo odpovědi, ne jen stavový kód. Odpověď 422 od dobře postaveného API pojmenuje konkrétní pole a pravidlo, které selhalo, což vám přesně řekne, co opravit, bez dalšího hádání.
2. Zkontrolujte pole proti zdokumentovaným omezením API, jako formát, délka, a povolené hodnoty, protože tohle jsou obchodní pravidla, která vám samotné schéma neukáže.
3. Berte 422 jako signál opravit data, ne opakovat požadavek beze změny. Opakování nezměněného požadavku, který selhal při validaci, selže pokaždé identicky; slušně se chovající klient by měl konkrétní chybu ukázat uživateli, ne ji potichu opakovat.

Pokud API provozujete

1. Vždy vraťte strukturované tělo chyby spolu s 422, pojmenujte pole a pravidlo, které selhalo, místo holého stavového kódu bez vysvětlení.
2. Udržujte validační chybové zprávy konkrétní a akční, například "email must be a valid address" místo obecného "validation failed", které nutí volajícího hádat, které z několika polí byl problém.
3. Záměrně rozhodněte mezi 400 a 422 pro své API a rozhodnutí zdokumentujte, aby integrátoři mohli postavit spolehlivé zpracování chyb místo toho, aby zacházeli s každou 4xx stejně.
4. Zaznamenávejte ověřená, ale odmítnutá data během vývoje, abyste zachytili případy, kdy váš vlastní klientský kód posílá data, která soustavně selhávají při validaci, což často ukazuje na nesoulad mezi klientem a skutečnými pravidly API.

Jak by měl klient zpracovat odpověď 422

Dobře navržený klient zachází s 422 jako s něčím zásadně jiným než chyba 5xx nebo selhání sítě: znamená to, že server je zdravý a funguje správně, a volající poslal něco, co server nikdy nepřijme v takové podobě. Správná reakce je zpracovat tělo chyby, namapovat každé selhané pole zpátky na formulář nebo vstup, který ho vyprodukoval, a ukázat uživateli něco akčního, ne to opakovat s odstupňovaným čekáním, jak byste to udělali u timeoutu nebo 503. Automatizované testy, které prověřují validační vrstvu API, by měly ověřovat konkrétní vrácené tělo chyby, ne jen stavový kód 422, protože právě to potvrzuje, že je správná samotná validační logika.

Jak předejít tomu, aby 422 zůstala bez povšimnutí

Validační pravidlo, které se neočekávaně změnilo, ať už kvůli nasazení, aktualizaci knihovny třetí strany, nebo migraci schématu, může potichu začít odmítat požadavky, které dřív uspěly. HTTP kontrola, která odešle známě funkční obsah a ověří očekávaný stavový kód, zachytí tuhle regresi okamžitě po nasazení. U API s víc než jedním endpointem, nebo obsahem, který samotný stavový kód nedokáže plně ověřit, monitoring API, který kontroluje i tělo odpovědi, potvrdí samotnou validační logiku, ne jen to, že je server dostupný.

Související chyby

Viz 400 Bad Request pro případ nedostupnosti zpracování požadavku, proti kterému tenhle návod staví do kontrastu, přehled 4xx pro širší rodinu, a 401 Unauthorized a 405 Method Not Allowed jinde v této dávce.

Často kladené otázky

Je 422 Unprocessable Entity totéž jako 422 Unprocessable Content?

Ano. RFC 9110 přejmenovalo důvodovou frázi na Unprocessable Content, ale je to stejný stavový kód se stejným významem; většina frameworků a dokumentace API pořád používá starší znění Unprocessable Entity.

Proč moje aplikace FastAPI vrací 422 pro chybějící pole?

FastAPI automaticky ověřuje data požadavku proti vašim modelům Pydantic, a chybějící povinné pole, nebo pole se špatným typem, tuhle validaci selže a vrátí 422 s tělem popisujícím přesně, které pole a pravidlo selhalo.

Měl bych opakovat požadavek, který dostal 422?

Jen poté, co změníte data, která selhala při validaci. Opakování identického požadavku vyprodukuje pokaždé identickou 422, protože server správně a konzistentně odmítá stejný neplatný vstup.

Jaký je v praxi rozdíl mezi 422 a 400?

400 je pro požadavek, který server vůbec nedokáže zpracovat. 422 je pro požadavek, který se v pořádku zpracuje, ale obsahuje hodnotu, která selže na validačním nebo obchodním pravidle. Hodně skutečných API používá 400 pro oba případy, takže si vždy zkontrolujte zdokumentovanou konvenci konkrétního API, které voláte.

Může 422 znamenat, že má server chybu?

Může, pokud je špatné samotné validační pravidlo, například odmítá skutečně platný formát e-mailu. Ale 422 podle návrhu znamená, že server funguje podle záměru a namítá proti datům, takže než usoudíte, že je rozbitý, prozkoumejte skutečné validační pravidlo.