422 Unprocessable Content

Usage

The 422 Unprocessable Content error indicates the server understands the request but finds the content semantically invalid. The content type is recognized (otherwise, a 415 Unsupported Media Type error is sent). The syntax is also valid (otherwise, a 400 Bad Request error is more appropriate).

An error of this type occurs when the request includes an XML instruction block as the message body, correctly formed and understood by the server, yet containing errors in logic resulting in a server-side error.

Example

The client uses an XML document to request starting task #100. The XML document is recognized by the server and syntactically correct. The server does not have a record of a task with id=100, so the request is not processable.

Request

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>

Response

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>

How to fix

Inspect the response body first. Most APIs and frameworks return field-level error details explaining which value failed and why. Use those messages to pinpoint the exact problem.

Validate the request body against the expected schema before sending. Common triggers include missing required fields, wrong data types (sending a string where the API expects a number), invalid email or date formats, duplicate unique values, and enum values outside the allowed set.

Confirm the Content-Type header matches the body format. Sending JSON with a text/plain content type leads to parsing failures on many servers.

In Laravel, a 422 typically means form validation rules were not satisfied. Check the errors object in the JSON response for the failing field names and validation messages. In Rails, failed model validations on create or update return 422 by default. Inspect model.errors for specifics.

For REST APIs like GitHub or Shopify, verify the request payload matches the current API version. Field names, required parameters, and accepted values change between versions.

On the server side, return structured error responses listing each invalid field, the rejected value, and the expected format. Generic “validation failed” messages force clients to guess.

Code references

.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