422 Unprocessable Content
The request is syntactically valid but semantically wrong, so the server cannot act on it.
Status
HTTP/1.1 422 Unprocessable Content
Details
- Category: 4xx
- Status: Standard. Registered with IANA and defined by a current standards-track RFC.
- Specification: RFC 9110 §15.5.21
- Cacheable: Only with explicit cache headers
- Response body: Allowed
- Retry: Retry only after changing the request
422 draws the line between parsing and meaning. The JSON parsed, the fields are the right types, and the server still cannot process it: an end date before a start date, a quantity below the minimum, a reference to a record that does not exist.
It began as a WebDAV code and was folded into the core HTTP semantics spec in RFC 9110. It is now the conventional validation-failure code for JSON APIs, and the response body should enumerate the specific failures rather than reporting one at a time.
Common causes
- Field-level validation failures on a well-formed body.
- Business rules rejecting an otherwise valid combination of values.
- A reference to an entity that does not exist or is not visible to the caller.
How to fix it
As the client
- Read the per-field errors in the body and correct the payload before resending.
- Do not retry unchanged. Nothing about the request will start working on its own.
As the server
- Return every validation error at once, keyed by field path, so clients do not iterate one fix at a time.
- Reserve 400 for unparsable input and 422 for input that parsed but failed validation. Mixing them makes client error handling guesswork.
Examples
POST /api/v2/order HTTP/1.1
Host: api.example.com
Content-Type: application/json
{"product_id":"isp-us","quantity":0}
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json; charset=utf-8
{"errors":[{"field":"quantity","rule":"min","min":1}]}