422 Unprocessable Entity: Bedeutung und Lösung

Was 422 Unprocessable Entity bedeutet

422 stammt aus WebDAV (RFC 4918) und wurde später von REST-APIs breit als Standardantwort für semantische Validierungsfehler übernommen. RFC 9110 hat den Statustext formal in 422 Unprocessable Content umbenannt und den WebDAV-spezifischen "Entity"-Wortlaut fallen gelassen, obwohl beide Namen denselben Statuscode beschreiben und "Unprocessable Entity" die weitaus üblichere Bezeichnung in Framework-Standardwerten und API-Dokumentation bleibt. Die wichtige Unterscheidung ist Syntax gegenüber Semantik: Das JSON wurde korrekt geparst, jeder Pflichtfeld-Typ passt, und die Anfrage ist nach jeder strukturellen Regel wohlgeformt, aber ein Wert darin verletzt eine Geschäftsregel, etwa eine E-Mail-Adresse im falschen Format, ein Datum in der Vergangenheit, wo ein zukünftiges Datum verlangt wird, oder ein Feld, das auf einen nicht existierenden Datensatz verweist.

Wie sich der Fehler zeigt

Ein 422 erscheint fast nie als Browser-Navigationsfehler, da er überwiegend eine API-Antwort ist, statt etwas, das ein Link oder ein Formular-Absenden direkt auslöst; er zeigt sich in einem Netzwerk-Tab, einer Fehlermeldung, oder einer gescheiterten Test-Assertion. Von der Kommandozeile aus liegt das nützliche Detail im Body der Antwort:

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

Die meisten gut gebauten APIs geben zusammen mit 422 einen strukturierten Fehler-Body zurück, der genau benennt, welches Feld gescheitert ist und warum, statt den Aufrufer allein aus dem Statuscode raten zu lassen.

Was einen 422 Unprocessable Entity verursacht

• Validierungsfehler in REST-APIs. Rails-Anwendungen geben üblicherweise automatisch 422 zurück, wenn ein ActiveRecord-Modell bei Erstellung oder Aktualisierung die Validierung nicht besteht. Laravels Form-Request-Validierung gibt standardmäßig 422 für gescheiterte Regeln zurück. FastAPI, aufgebaut auf Pydantic, gibt 422 zurück, wann immer Anfragedaten die Typ- oder Constraint-Prüfungen eines Pydantic-Modells nicht bestehen, weshalb es speziell in FastAPI-Projekten einer der am häufigsten gesehenen Statuscodes ist.
• Ein Feld mit richtigem Typ, aber ungültigem Wert. Ein String, wo ein String erwartet wurde, der aber eine Formatprüfung, ein Längenlimit, oder eine Liste erlaubter Werte nicht besteht.
• Ein Verweis auf etwas, das nicht existiert. Ein Fremdschlüssel, eine Nutzer-ID, oder ein Slug im Anfrage-Body, der syntaktisch in Ordnung ist, aber keinem echten Datensatz entspricht.
• Geschäftsregeln jenseits einfacher Feldvalidierung. Ein Rabattcode, der syntaktisch gültig, aber abgelaufen ist, oder eine Menge, die eine gültige Ganzzahl ist, aber den verfügbaren Bestand überschreitet.
• Ein Pflichtfeld fehlt vollständig. Je nach Framework kann ein fehlendes Pflichtfeld 422 statt 400 zurückgeben, da die Anfrage einwandfrei parst, ihr aber ein von der Validierungsschicht verlangter Wert fehlt.

422 gegenüber 400

Die Grenze liegt bei Syntax gegenüber Semantik. 400 Bad Request bedeutet, der Server konnte die Anfrage überhaupt nicht parsen, zum Beispiel fehlerhaftes JSON oder ein Body, der nach keiner strukturellen Regel gültig ist. 422 bedeutet, die Anfrage wurde problemlos geparst, und jedes Feld hat den richtigen Typ, aber ein Wert darin scheitert an einer Regel, die die Anwendung nach dem Parsen prüft. In der Praxis verwischen viele APIs diese Unterscheidung und nutzen 400 für beide Fälle, was vertretbar, aber weniger präzise ist; ein Client, der gegen eine API integriert, sollte den Antwort-Body lesen, statt sich allein auf den Statuscode zu verlassen, um genau zu wissen, was gescheitert ist.

So beheben Sie einen 422-Fehler

Sind Sie ein Client, der eine API aufruft

1. Lesen Sie den Antwort-Body, nicht nur den Statuscode. Die 422-Antwort einer gut gebauten API benennt das konkrete Feld und die Regel, die gescheitert ist, was Ihnen genau sagt, was zu korrigieren ist, ohne weiter raten zu müssen.
2. Prüfen Sie das Feld gegen die dokumentierten Einschränkungen der API, etwa Format, Länge, und erlaubte Werte, da das Geschäftsregeln sind, die das Schema allein nicht zeigt.
3. Behandeln Sie 422 als Signal, die Daten zu korrigieren, nicht die unveränderte Anfrage zu wiederholen. Eine unveränderte Anfrage, die die Validierung nicht bestanden hat, erneut zu senden, scheitert jedes Mal identisch; ein gut gebauter Client sollte den konkreten Fehler dem Nutzer zeigen, statt still erneut zu versuchen.

Betreiben Sie die API

1. Geben Sie immer einen strukturierten Fehler-Body zurück zusammen mit 422, der das gescheiterte Feld und die Regel benennt, statt eines nackten Statuscodes ohne Erklärung.
2. Halten Sie Validierungsfehlermeldungen konkret und umsetzbar, zum Beispiel "email muss eine gültige Adresse sein" statt eines generischen "validation failed", das den Aufrufer zwingt zu raten, welches von mehreren Feldern das Problem war.
3. Entscheiden Sie bewusst zwischen 400 und 422 für Ihre API und dokumentieren Sie die Wahl, damit Integratoren zuverlässige Fehlerbehandlung bauen können, statt jeden 4xx gleich zu behandeln.
4. Protokollieren Sie die validierten, aber abgelehnten Payloads während der Entwicklung, um Fälle zu erkennen, in denen Ihr eigener Client-Code konsequent Daten sendet, die die Validierung nicht bestehen, was oft auf eine Fehlpassung zwischen dem Client und den tatsächlichen Regeln der API hindeutet.

Wie ein Client eine 422-Antwort behandeln sollte

Ein gut gestalteter Client behandelt 422 als grundlegend anders als einen 5xx-Fehler oder einen Netzwerkfehler: Es bedeutet, der Server ist gesund und arbeitet korrekt, und der Aufrufer hat etwas gesendet, das der Server so nie akzeptieren wird. Die richtige Reaktion ist, den Fehler-Body zu parsen, jedes gescheiterte Feld auf das Formular oder die Eingabe zurückzuführen, die es erzeugt hat, und dem Nutzer etwas Umsetzbares zu zeigen, nicht mit Backoff erneut zu versuchen, wie Sie es bei einer Zeitüberschreitung oder einem 503 tun würden. Automatisierte Tests, die die Validierungsschicht einer API prüfen, sollten auf den konkreten zurückgegebenen Fehler-Body prüfen, nicht nur auf den 422-Statuscode, da das bestätigt, dass die Validierungslogik selbst korrekt ist.

So verhindern Sie, dass 422er unbemerkt bleiben

Eine Validierungsregel, die sich unerwartet geändert hat, sei es durch ein Deploy, ein Update einer Drittanbieter-Bibliothek, oder eine Schema-Migration, kann still anfangen, Anfragen abzulehnen, die früher erfolgreich waren. Eine HTTP-Prüfung, die einen bekannt guten Payload sendet und auf den erwarteten Statuscode prüft, erkennt diese Regression sofort nach einem Deploy. Für APIs mit mehr als einem Endpunkt oder einem Payload, den der Statuscode allein nicht vollständig verifizieren kann, bestätigt API-Monitoring, das auch den Antwort-Body prüft, die Validierungslogik selbst, nicht nur, dass der Server erreichbar ist.

Verwandte Fehler

Siehe 400 Bad Request für den Fall, dass die Anfrage nicht geparst werden konnte, gegen den diese Anleitung 422 abgrenzt, die 4xx-Übersicht für die breitere Familie, und 401 Unauthorized und 405 Method Not Allowed anderswo in dieser Gruppe.

Häufig gestellte Fragen

Ist 422 Unprocessable Entity dasselbe wie 422 Unprocessable Content?

Ja. RFC 9110 hat die Reason Phrase in Unprocessable Content umbenannt, aber es ist derselbe Statuscode mit derselben Bedeutung; die meisten Frameworks und API-Dokumentationen nutzen weiterhin den älteren Wortlaut Unprocessable Entity.

Warum gibt meine FastAPI-Anwendung bei einem fehlenden Feld 422 zurück?

FastAPI validiert Anfragedaten automatisch gegen Ihre Pydantic-Modelle, und ein fehlendes Pflichtfeld, oder eines mit falschem Typ, scheitert an dieser Validierung und gibt 422 mit einem Body zurück, der genau beschreibt, welches Feld und welche Regel gescheitert sind.

Sollte ich eine Anfrage wiederholen, die einen 422 bekommen hat?

Nur nachdem Sie die Daten geändert haben, die die Validierung nicht bestanden haben. Die identische Anfrage zu wiederholen erzeugt jedes Mal den identischen 422, da der Server dieselbe ungültige Eingabe korrekt und konsequent ablehnt.

Was ist der Unterschied zwischen 422 und 400 in der Praxis?

400 ist für eine Anfrage, die der Server überhaupt nicht parsen kann. 422 ist für eine Anfrage, die einwandfrei parst, aber einen Wert enthält, der eine Validierungs- oder Geschäftsregel nicht besteht. Viele reale APIs nutzen 400 für beides, prüfen Sie also immer die dokumentierte Konvention der konkreten API, die Sie aufrufen.

Kann ein 422 bedeuten, dass der Server einen Fehler hat?

Kann sein, falls die Validierungsregel selbst falsch ist, zum Beispiel indem sie ein tatsächlich gültiges E-Mail-Format ablehnt. Aber ein 422 bedeutet per Design, dass der Server wie beabsichtigt arbeitet und den Daten widerspricht, untersuchen Sie also die tatsächliche Validierungsregel, bevor Sie annehmen, sie sei kaputt.