HTTP Status 422 - Unprocessable Entity

Der HTTP-Status-Code 422 Unprocessable Entity signalisiert, dass Request syntaktisch korrekt ist, aber semantische Errors enthält. Server kann Request nicht verarbeiten wegen Business-Rule-Violations, logischen Inkonsistenzen oder Datentyp-Problemen. Häufig in REST-APIs für Validation-Errors.

Typ

Response-Status-Code

Syntax

Der Status Code wird zurückgegeben bei semantischen Validation Errors.

http
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

Direktiven

Der 422 Unprocessable Entity Status Code wird für semantische Validation verwendet.

Semantic Validation
Request ist syntaktisch korrekt (valid JSON/XML, korrekte Headers), aber semantisch ungültig (Business-Rules verletzt, logische Constraints nicht erfüllt).
Structured Error Response
Response sollte detaillierte Validation-Errors pro Field enthalten. Ermöglicht Client-seitige Error-Display und Field-Highlighting.
Unterschied zu 400
400 für Syntax-Errors (malformed JSON, missing Headers), 422 für semantische Errors (negative Age, invalid State-Transition, Business-Constraint-Violation).

Beispiele

Nachfolgend finden Sie praktische Anwendungsbeispiele für Status 422.

Beispiel 1 Business Rule Violation

http
POST /api/orders HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"product_id": 42, "quantity": -5, "shipping_address": ""}

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": "validation_failed",
  "message": "Request contains semantic errors",
  "errors": [
    {
      "field": "quantity",
      "value": -5,
      "message": "Must be a positive integer",
      "code": "positive_integer_required"
    },
    {
      "field": "shipping_address",
      "value": "",
      "message": "Required for physical products",
      "code": "required_field"
    }
  ]
}

Beispiel 2 Logical Inconsistency

http
POST /api/events HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"title": "Meeting", "start": "2025-10-01T15:00:00Z", "end": "2025-10-01T14:00:00Z"}

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": "invalid_time_range",
  "message": "Event end time must be after start time",
  "start": "2025-10-01T15:00:00Z",
  "end": "2025-10-01T14:00:00Z"
}

Beispiel 3 State Transition Error

http
POST /api/invoices/inv-123/pay HTTP/1.1
Host: api.example.com

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": "invalid_state",
  "message": "Cannot pay invoice in 'cancelled' state",
  "current_state": "cancelled",
  "valid_states_for_payment": ["pending", "overdue"]
}

Semantic Validation Flow

422 Unprocessable Entity bei Business Rule Validation Failure

Vorteile für die Systemarchitektur

  • Clear Validation Semantics: Unterscheidet Syntax-Errors (400) von Semantic-Errors (422). Client kann gezielt UI-Validation implementieren basierend auf Error-Type.
  • Field-Level Error Details: Strukturierte Error-Responses pro Field ermöglichen granulares Error-Display in Forms. Verbessert User Experience durch präzises Feedback.
  • Business Logic Enforcement: Validierung von Business-Rules auf API-Level verhindert Invalid-State in Backend. Ensures Data-Integrity vor Database-Insert.

Spezifikation

RFC 4918, Section 11.2 – WebDAV https://www.rfc-editor.org/rfc/rfc4918.html#section-11.2

Weitere Spezifikationen

HTTP Status 400 - Bad Request, Content-Type Header