422 Unprocessable Entity: wat het betekent en hoe u het oplost

Wat 422 Unprocessable Entity betekent

422 ontstond in WebDAV (RFC 4918) en werd later breed overgenomen door REST-API's als het standaardantwoord voor semantische validatiestoringen. RFC 9110 hernoemde de statustekst formeel naar 422 Unprocessable Content, waarbij de WebDAV-specifieke bewoording "Entity" verviel, al beschrijven beide namen dezelfde statuscode en blijft "Unprocessable Entity" verreweg het gebruikelijkere label in frameworkstandaarden en API-documentatie. Het onderscheid dat ertoe doet is syntaxis versus semantiek: de JSON parseerde correct, elk verplicht veldtype klopt, en het verzoek is volgens elke structurele regel welgevormd, maar een waarde erin schendt een bedrijfsregel, zoals een e-mailadres in het verkeerde formaat, een datum in het verleden waar een toekomstige datum vereist is, of een veld dat verwijst naar een record dat niet bestaat.

Hoe de fout verschijnt

Een 422 verschijnt vrijwel nooit als een navigatiefout in de browser, aangezien het overwegend een API-antwoord is in plaats van iets dat een link of formulierinzending rechtstreeks triggert; hij verschijnt in een netwerktabblad, een foutmelding, of een mislukte testassertie. Vanaf de commandoregel zit het nuttige detail in de body van het antwoord:

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

De meeste goed gebouwde API's geven naast 422 een gestructureerde foutbody terug, die precies noemt welk veld faalde en waarom, in plaats van de aanroeper alleen op basis van de statuscode te laten gokken.

Wat een 422 Unprocessable Entity veroorzaakt

• Validatiefouten in REST-API's. Rails-applicaties geven vaak automatisch 422 terug wanneer een ActiveRecord-model faalt bij validatie tijdens aanmaken of bijwerken. De formulierrequestvalidatie van Laravel geeft standaard 422 terug bij mislukte regels. FastAPI, gebouwd op Pydantic, geeft 422 terug zodra requestdata een type- of beperkingscontrole van een Pydantic-model niet doorstaat, wat is waarom het een van de vaakst geziene statuscodes is specifiek in FastAPI-projecten.
• Een veld met het juiste type maar een ongeldige waarde. Een string waar een string verwacht werd, maar een die een formaatcontrole, een lengtelimiet, of een lijst van toegestane waarden niet doorstaat.
• Een verwijzing naar iets dat niet bestaat. Een foreign key, gebruikers-id, of slug in de requestbody die syntactisch prima is maar niet overeenkomt met een echt record.
• Bedrijfsregels die verder gaan dan eenvoudige veldvalidatie. Een kortingscode die syntactisch geldig is maar verlopen, of een hoeveelheid die een geldig geheel getal is maar de beschikbare voorraad overschrijdt.
• Een verplicht veld dat volledig ontbreekt. Afhankelijk van het framework kan een ontbrekend verplicht veld 422 teruggeven in plaats van 400, aangezien het verzoek prima parseert, het ontbreekt alleen aan een waarde die de validatielaag vereist.

422 versus 400

De lijn is syntaxis versus semantiek. 400 Bad Request betekent dat de server het verzoek helemaal niet kon parseren, bijvoorbeeld misvormde JSON of een body die volgens geen enkele structurele regel geldig is. 422 betekent dat het verzoek probleemloos parseerde, en elk veld het juiste type heeft, maar een waarde erin een regel schendt die de applicatie na het parseren controleert. In de praktijk vervagen veel API's dit onderscheid en gebruiken ze 400 voor beide gevallen, wat verdedigbaar is maar minder precies; een client die tegen een API integreert moet de responsbody lezen in plaats van alleen op de statuscode te vertrouwen om precies te weten wat faalde.

Hoe u een 422-fout oplost

Bent u een client die een API aanroept

1. Lees de responsbody, niet alleen de statuscode. Het 422-antwoord van een goed gebouwde API noemt het specifieke veld en de regel die faalde, wat u precies vertelt wat te corrigeren zonder verder te gokken.
2. Controleer het veld tegen de gedocumenteerde beperkingen van de API zoals formaat, lengte, en toegestane waarden, aangezien dit bedrijfsregels zijn die het schema alleen u niet zal tonen.
3. Behandel 422 als een signaal om de data te herstellen, niet om het verzoek onveranderd opnieuw te proberen. Een ongewijzigd verzoek dat faalde bij validatie opnieuw proberen levert elke keer identiek dezelfde 422 op; een goed werkende client hoort de specifieke fout aan de gebruiker te tonen in plaats van stilzwijgend opnieuw te proberen.

Beheert u de API

1. Geef altijd een gestructureerde foutbody terug naast 422, die het veld en de regel noemt die faalde, in plaats van een kale statuscode zonder uitleg.
2. Houd validatiefoutmeldingen specifiek en bruikbaar, bijvoorbeeld "e-mail moet een geldig adres zijn" in plaats van een generieke "validatie mislukt" die de aanroeper dwingt te gokken welk van de meerdere velden het probleem was.
3. Kies bewust tussen 400 en 422 voor uw API en documenteer die keuze, zodat integrators betrouwbare foutafhandeling kunnen bouwen in plaats van elke 4xx hetzelfde te behandelen.
4. Log gevalideerde-maar-geweigerde payloads tijdens de ontwikkeling om gevallen op te vangen waarin uw eigen clientcode consequent data stuurt die faalt bij validatie, wat vaak wijst op een mismatch tussen de client en de daadwerkelijke regels van de API.

Hoe een client een 422-antwoord moet afhandelen

Een goed ontworpen client behandelt 422 als fundamenteel anders dan een 5xx-fout of een netwerkstoring: het betekent dat de server gezond is en correct werkt, en dat de aanroeper iets stuurde dat de server nooit zo zal accepteren. De juiste reactie is de foutbody te parseren, elk mislukt veld terug te koppelen aan het formulier of de invoer die het produceerde, en de gebruiker iets bruikbaars te tonen, niet opnieuw te proberen met backoff zoals u zou doen bij een timeout of een 503. Geautomatiseerde tests die de validatielaag van een API testen zouden moeten controleren op de specifieke teruggegeven foutbody, niet alleen op de 422-statuscode, aangezien dat bevestigt dat de validatielogica zelf correct is.

Hoe u voorkomt dat 422's onopgemerkt blijven

Een validatieregel die onverwacht wijzigde, ofwel door een deployment, een update van een bibliotheek van derden, of een schemamigratie, kan stilletjes verzoeken beginnen weigeren die vroeger slaagden. Een HTTP-controle die een bekend geldige payload verstuurt en toetst op de verwachte statuscode vangt dat soort regressie meteen na een deployment. Voor API's met meer dan één endpoint of een payload die de statuscode alleen niet volledig kan verifiëren, bevestigt API-monitoring die ook de responsbody controleert de validatielogica zelf, niet alleen dat de server bereikbaar is.

Gerelateerde fouten

Zie 400 Bad Request voor het geval waarbij het verzoek niet kon parseren, waar deze handleiding het mee contrasteert, het 4xx-overzicht voor de bredere familie, en 401 Unauthorized en 405 Method Not Allowed elders in deze reeks.

Veelgestelde vragen

Is 422 Unprocessable Entity hetzelfde als 422 Unprocessable Content?

Ja. RFC 9110 hernoemde de reason phrase naar Unprocessable Content, maar het is dezelfde statuscode met dezelfde betekenis; de meeste frameworks en API-documentatie gebruiken nog steeds de oudere bewoording Unprocessable Entity.

Waarom geeft mijn FastAPI-app 422 terug bij een ontbrekend veld?

FastAPI valideert requestdata automatisch tegen uw Pydantic-modellen, en een ontbrekend verplicht veld, of een met het verkeerde type, faalt bij die validatie en geeft 422 terug met een body die precies beschrijft welk veld en welke regel faalde.

Moet ik een verzoek dat een 422 kreeg opnieuw proberen?

Alleen nadat u de data die faalde bij validatie heeft gewijzigd. Het identieke verzoek opnieuw proberen levert elke keer dezelfde 422 op, aangezien de server correct en consistent dezelfde ongeldige invoer weigert.

Wat is het verschil tussen 422 en 400 in de praktijk?

400 is voor een verzoek dat de server helemaal niet kan parseren. 422 is voor een verzoek dat prima parseert maar een waarde bevat die een validatie- of bedrijfsregel schendt. Veel praktische API's gebruiken 400 voor beide, dus controleer altijd de gedocumenteerde conventie voor de specifieke API die u aanroept.

Kan een 422 op een bug in de server wijzen?

Dat kan, als de validatieregel zelf verkeerd is, bijvoorbeeld een echt geldig e-mailformaat weigeren. Maar een 422 betekent per ontwerp dat de server werkt zoals bedoeld en bezwaar maakt tegen de data, dus onderzoek de daadwerkelijke validatieregel voordat u aanneemt dat er iets kapot is.