What Is a 422 Unprocessable Content Error?

A 422 means the server understood your request perfectly and rejected the data inside it.

The content type was right. The JSON parsed. But something in the values failed a business rule: a missing required field, a string where a number belongs, an email that is not an email, a date in the past that had to be in the future.

Note the name. RFC 9110 renamed 422 from Unprocessable Entity to Unprocessable Content in 2022. Most tooling still says Entity, and both refer to the same status code.

01422 vs 400 vs 415

These three are the reason 422 gets misused, and the distinction is precise.

RFC 9110 defines 422 by exclusion: the content type is understood, so 415 is inappropriate, and the syntax is correct, so 400 is inappropriate, but the server could not process the instructions.

The rule of thumb: if a JSON parser would fail, it is a 400. If a parser succeeds and your validator fails, it is a 422.

02What Causes a 422

Six things, in rough order of frequency:

1. A required field is missing. The most common cause by far.
2. Wrong data type. Sending "42" where the API expects 42, or a string where it wants a boolean.
3. A format rule failed. Email addresses, dates, phone numbers, UUIDs, postcodes.
4. A value is outside its allowed set. An enum field receiving something not on the list.
5. A uniqueness constraint failed. Creating a user with an email that already exists.
6. A cross-field rule failed. An end date before a start date. Each field is individually valid and the combination is not.

03How To Fix It

Read the response body first. A well-built API returns which field failed and why. This is the whole fix in most cases and people skip it because they only looked at the status code.

Check your Content-Type header. Sending JSON with text/plain causes parsing oddities that surface as validation failures on some servers.

Validate against the schema before sending. If the API publishes an OpenAPI spec, validate your payload against it locally. Faster than a round trip.

Check the API version. Field names and required parameters change between versions. A payload that worked last quarter may not now.

Framework specifics worth knowing: in Laravel, a 422 usually means form validation rules failed, and the errors object names the fields. In Rails, failed model validations on create or update return 422 by default, so check model.errors. In Django REST Framework, serializer validation errors return 400 rather than 422, which catches people moving between stacks.

04A Worked Example

You create a user:

http

POST /users HTTP/1.1
Content-Type: application/json

{"name": "Ada", "email": "ada-at-example.com", "age": "thirty"}

The response:

http

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

{
  "errors": [
    {"field": "email", "message": "must be a valid email address"},
    {"field": "age", "message": "must be an integer"}
  ]
}

The JSON was valid. Both values were not. That is a 422, and the body tells you exactly what to change.

05Should Your API Return 422?

If you build APIs, this is worth deciding deliberately.

Return 422 when the request parsed and your validation rejected the values. Include which fields failed and why, because an error naming the field is one someone can fix. An error saying "validation failed" is one that generates a support ticket.

Return 400 when the request could not be parsed at all.

Some large APIs use 400 for both, and that is a defensible simplification. What is not defensible is returning 200 with an error object in the body, which breaks every client that checks status codes.

Validating data before it reaches your API avoids most of this. Validation endpoints for emails, phone numbers, VAT and IBAN numbers check values against live sources rather than format rules alone.

Try a validation endpoint free - 5 calls a day, no card.

06FAQ

What is the difference between 400 and 422?

A 400 means the server could not parse your request, usually malformed syntax. A 422 means it parsed fine and the values inside failed validation. If a JSON parser would choke, it is a 400.

Is it Unprocessable Entity or Unprocessable Content?

Both. RFC 9110 renamed the status from Unprocessable Entity to Unprocessable Content in 2022. Most libraries and error messages still use the older name and mean the same thing.

What is the difference between 415 and 422?

A 415 means the server does not accept the format you sent, such as XML to a JSON-only endpoint. A 422 means the format was fine and the data inside was not.

Why am I getting a 422 when my JSON looks correct?

Correct JSON syntax is not the issue. Something in the values failed a rule: a missing required field, a wrong type, a bad email format, or a cross-field constraint. Read the response body, which usually names the field.

Does a 422 mean my API key is wrong?

No. That is a 401 for a missing or invalid key, or 403 for a valid key without permission. A 422 means you were authenticated and the data was rejected.

Should I retry a 422?

Not without changing the request. A 422 is deterministic: the same payload will fail the same way every time. Fix the data first.

07Related

• 405 Method Not Allowed - when the verb is wrong rather than the data
• Data Validation APIs - catching bad values before they reach an API
• API Fundamentals - status codes from scratch

Source: RFC 9110, section 15.5.21

08About ApyHub

ApyHub is a curated API catalog for developers, teams and AI agents: file conversion, data validation, OCR and extraction and more across 20 categories. One key covers all of it, every endpoint is MCP-ready so AI agents can discover and call them directly, and every service page has a playground for testing before you build.

EU-based and EU-hosted, which keeps data residency simple for teams with GDPR obligations.

Browse the catalog | Get a free API key - no credit card required.