422 Unprocessable Content

Verwendung

Der Fehler 422 Unprocessable Content zeigt an, dass der Server die Anfrage versteht, den Inhalt jedoch für semantisch ungültig hält. Der Content-Type wird erkannt (andernfalls würde ein Fehler 415 Unsupported Media Type gesendet). Auch die Syntax ist gültig (andernfalls wäre ein Fehler 400 Bad Request passender).

Ein Fehler dieser Art tritt auf, wenn die Anfrage einen XML-Anweisungsblock als Nachrichten-Body enthält, der korrekt aufgebaut und vom Server verstanden wird, aber Logikfehler enthält, die zu einem serverseitigen Fehler führen.

Hinweis

Eine 422-Anfrage erneut zu senden, ohne den Anfrage-Body zu ändern, erzeugt denselben Fehler. Der Client muss zuerst das Validierungsproblem beheben. Geben Sie 422 zurück, wenn der Content-Type erkannt wird und die Syntax gültig ist, Geschäftsregeln oder die Feldvalidierung die Daten jedoch zurückweisen.

SEO-Auswirkung

Suchmaschinen wie Google indexieren keine URL mit dem Antwortstatus 422 Unprocessable Content; folglich werden in der Vergangenheit indexierte URLs, die diesen HTTP-Statuscode zurückgeben, aus den Suchergebnissen entfernt.

Beispiel

Der Client verwendet ein XML-Dokument, um den Start von Aufgabe #100 anzufordern. Das XML-Dokument wird vom Server erkannt und ist syntaktisch korrekt. Der Server hat keinen Eintrag für eine Aufgabe mit id=100, daher ist die Anfrage nicht verarbeitbar.

Anfrage

POST /requests HTTP/1.1
Host: example.com
Content-Type: application/xml
Content-Length: 101

<?xml version="1.0" encoding="utf-8"?>
<request>
   <id>100</id>
   <action>start</action>
</request>

Antwort

HTTP/1.1 422 Unprocessable Content
Content-Type: text/html
Content-Length: 150

<html>
  <head>
    <title>Request Failed</title>
  </head>
  <body>
   <p>Task #100 is not recognized.</p>
  </body>
</html>

Behebung

Sehen Sie sich zuerst den Antwort-Body an. Die meisten APIs und Frameworks geben Fehlerdetails auf Feldebene zurück, die erklären, welcher Wert fehlgeschlagen ist und warum. Nutzen Sie diese Meldungen, um das genaue Problem einzugrenzen.

Validieren Sie den Anfrage-Body vor dem Senden gegen das erwartete Schema. Häufige Auslöser sind fehlende Pflichtfelder, falsche Datentypen (ein String, wo die API eine Zahl erwartet), ungültige E-Mail- oder Datumsformate, doppelte eindeutige Werte und Enum-Werte außerhalb der erlaubten Menge.

Stellen Sie sicher, dass der Content-Type-Header zum Format des Body passt. JSON mit dem Content-Type text/plain zu senden, führt auf vielen Servern zu Parsing-Fehlern.

In Laravel bedeutet ein 422 typischerweise, dass die Formular-Validierungsregeln nicht erfüllt wurden. Prüfen Sie das errors-Objekt in der JSON-Antwort auf die fehlgeschlagenen Feldnamen und Validierungsmeldungen. In Rails geben fehlgeschlagene Modellvalidierungen bei create oder update standardmäßig 422 zurück. Untersuchen Sie model.errors für Details.

Prüfen Sie bei REST-APIs wie GitHub oder Shopify, ob die Anfrage-Nutzlast zur aktuellen API-Version passt. Feldnamen, Pflichtparameter und zulässige Werte ändern sich zwischen Versionen.

Geben Sie serverseitig strukturierte Fehlerantworten zurück, die jedes ungültige Feld, den abgelehnten Wert und das erwartete Format auflisten. Allgemeine „validation failed“-Meldungen zwingen Clients zum Raten.

Code-Referenzen

.NET

HttpStatusCode.UnprocessableEntity

Rust

http::StatusCode::UNPROCESSABLE_ENTITY

Rails

:unprocessable_entity

http.StatusUnprocessableEntity

Symfony

Response::HTTP_UNPROCESSABLE_ENTITY

Python3.5+

http.HTTPStatus.UNPROCESSABLE_ENTITY

Apache HttpComponents Core

org.apache.hc.core5.http.HttpStatus.SC_UNPROCESSABLE_CONTENT
// deprecated alias: SC_UNPROCESSABLE_ENTITY

Angular

@angular/common/http/HttpStatusCode.UnprocessableEntity