HTTP 422 Unprocessable Content – Free, Online, Private

What HTTP 422 means

422 says the server understood the content type and the syntax, and it cannot process the instructions. The older phrase was Unprocessable Entity. WebDAV defined it. JSON APIs use it for a body that parses and still violates a rule, when they want that distinguished from a 400 parse error. The body should list the problems. A bare 422 is only a little better than a bare 400.

422 Unprocessable Content belongs to the 4xx client error class. Clients that only look at the class will group it with its neighbors. Clients that care about the exact code should use the narrower rule on this page, because the class is only the first digit.

When you see HTTP 422

When you see HTTP 422 Unprocessable Content, stop on that exact status line. 422 Unprocessable Content means the syntax was fine and the instructions could not be followed. The trace that usually produces it: JSON parsed and a date field was in the past when the API requires the future. The 4xx client error class only tells you the first digit. A neighbor in that class is a different fault, and the fix on this page does not transfer to it.

Return 422 when the document is well formed and semantically unacceptable. Return 400 when it does not parse. Return 409 when the failure depends on another writer's state rather than on this document. Be consistent. An API that uses 400 for everything does not need 422. An API that uses both must say which is which.

How to fix HTTP 422

To fix HTTP 422, change the condition that made the server choose Unprocessable Content. Change the document and resend. Do not retry the same body. Branch on the field errors if you render a form. Do not treat 422 as temporary. Only after the body changes. The same body is still unprocessable. If the log line is a different code, leave this page. The mix-up people make with 422 is this one: 400 is often syntax. 409 is a conflict with current state. 415 is the wrong type. 422 is a type you accepted and a meaning you rejected.

• An XML document was well formed and failed a WebDAV precondition that is not an HTTP precondition.
• A client retried the same body and got the same 422.
• The error list named fields the client had not sent, because the server validated a merged object and reported it badly.

An access log that only stores 422 is not enough to tell these apart. Keep the method, the path, and a request id. Do not keep the Authorization header or a request body that might be a token. The status explains the outcome. It is not a place to echo secrets back to the client either.

Example response

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

{"errors":[{"field":"start","message":"must be in the future"}]}

The errors array is the contract. Point at fields the client sent. A 422 without a machine-readable list becomes a stringly-typed 400. Keep the status for the class of failure, and keep the list for the details.

What the client should do

Change the document and resend. Do not retry the same body. Branch on the field errors if you render a form. Do not treat 422 as temporary.

Do not cache 422 as the resource. It describes a rejected write.

Only after the body changes. The same body is still unprocessable.

Codes people confuse with HTTP 422

400 is often syntax. 409 is a conflict with current state. 415 is the wrong type. 422 is a type you accepted and a meaning you rejected.