subscribe

422 Unprocessable Entity

The 422 Unprocessable Entity status-code does not appear in the base HTTP specification. Like 102 and 207 it’s part of the WebDAV specification, which is an extension to HTTP.

Unlike the other two, the 422 code has a good general use-case, and is often used in Web API’s.

The 422 code implies that the server understood the general syntax of the request, but the contents were incorrect. For example, a server might expect POST requests that uses the application/json format. If the request is broken JSON, it might be more appropriate to send back the 400 status code, but if the request is valid JSON but the request doesn’t pass validation (via for example json-schema) returning 422 might be better.

If there was something wrong with the request body, you can use the following rules to figure out what to send back:

  • If the Content-Type was not supported, use 415.
  • Else: If the request was not parsable (broken JSON, XML), use 400 Bad Request.
  • Else: If the request was parsable but the specific contents of the payload were wrong (due to validation or otherwise), use 422

Example

POST /new-article HTTP/1.1
Content-Type: application/json

{ "title": "Hello world!"}

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

{
  "type" : "https://example/errors/missing-property",
  "status": 422,
  "title": "Missing property: body"
}

References

HTTP series

This article is part of a series about the HTTP protocol. Read them all here:

Informational 1xx

Successful 2xx

Redirection 3xx

Client Error 4xx

Server Error 5xx

Web mentions