The 422 Unprocessable Entity: The JSON Parsed but a Validation Rule Rejected It

Quick answer: A 422 Unprocessable Entity means the server understood the request, the content type is correct, and the body parsed, but the data failed a semantic validation rule. It is not a syntax error like a 400 from malformed JSON. To debug it, read the returned field-level errors, reproduce the exact payload, and find the business rule that rejected it, such as a date range that points backward or a reference to a record that does not exist.

Where 422 sits in the error hierarchy

Status codes are most useful when you read them in order. A 400 usually means the request could not be parsed at all, a 415 means the media type is unsupported, and a 422 means the document is well-formed but logically invalid. The server got far enough to validate the meaning of the data, which is why a 422 response typically carries a structured list of field problems rather than a single generic message.

A realistic 422

Imagine a booking request that serializes perfectly. The JSON is valid and the content type is correct, but the end date is earlier than the start date. The server rejects it with a 422 and names the offending fields.

// Request
{
  "roomId": "r-208",
  "startDate": "2026-11-10",
  "endDate": "2026-11-08"
}

// Response: 422
{
  "type": "https://example.com/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "errors": [
    {
      "field": "endDate",
      "rule": "date-after",
      "message": "endDate must be later than startDate"
    }
  ]
}

The important detail is that no single field is malformed; the rule spans two fields and only fails when they are compared. That is the hallmark of a 422: the violation is in the relationship between values, not in their syntax.

Debugging steps

1. Capture the exact body and headers that failed, not a paraphrase, because a missing optional field or a string where a number is expected can change the rule path.
2. Read the field and rule names in the response. A well-designed API tells you which constraint failed, which points directly at the validation logic.
3. Reproduce the call in isolation so you can vary one field at a time and confirm which rule triggers the 422.
4. Check whether the client transformed a value before sending, such as formatting a date into a different timezone or coercing an ID into a string.

Cross-field and referential rules

Many 422s are referential rather than arithmetic. A foreign key can point at a record that the tenant cannot see, a status transition can be invalid for the current state, or a discount can be applied to an order that no longer qualifies. These rules cannot be checked by a JSON schema alone, which is why they live in application code and why a client-side schema validation will not catch them. If you find yourself guessing, ask the server to enumerate the rule rather than hardcoding against one message string.

How an agent misreads it

An agent that sees a 422 sometimes treats it like a malformed request and starts reformatting the JSON, which does nothing because the syntax is already fine. A better prompt asks the agent to map each returned error to a validation rule and propose a payload that satisfies all of them, rather than changing the encoding. If the agent's fix is to add a generic retry, reject it: a 422 is deterministic and will keep failing until the data changes, so retrying the same body is pointless.

Standardizing the shape

When you control the API, return a consistent validation structure with a field pointer, a rule identifier, and a human-readable message, ideally following the RFC 9457 problem-details format with an extension for validation errors. Stable rule identifiers let clients and tests assert on the specific constraint instead of brittle message text, and they make the 422 genuinely debuggable rather than a black box.

Confirming the fix end to end

Once you change the payload, verify the happy path rather than assuming the 422 is gone. Send the corrected request and confirm a success code, then deliberately reintroduce each bad value and confirm the 422 names the rule you expect. This mutation check is valuable because it proves the validation is actually wired to the field and not merely present in the response of one case. Keep these two requests, the failing and the corrected one, as a regression pair so the rule stays covered if the validation logic is refactored later.

# The failing body, kept to prove the rule fires
curl -s -o /dev/null -w "%{http_code}\n" \
  -X POST https://api.example.com/bookings \
  -H "Content-Type: application/json" \
  -d @bad-booking.json
# 422

# The corrected body, which satisfies the date-after rule
curl -s -o /dev/null -w "%{http_code}\n" \
  -X POST https://api.example.com/bookings \
  -H "Content-Type: application/json" \
  -d @good-booking.json
# 201

Recording the request ID from the failed call alongside the regression pair also helps when you need to trace the validation through the server logs, which is faster than reproducing the payload from memory weeks later.

Frequently asked questions

Is 422 a client or server error?

It is a client error in the 4xx range. The server is working correctly; the submitted data is syntactically valid but violates a semantic rule.

How is 422 different from 400?

A 400 means the request could not be parsed or is structurally invalid, while a 422 means it parsed fine but the values fail a business or cross-field validation rule.

Should I retry a 422?

Not with the same payload. A 422 is deterministic, so you must change the data to satisfy the rule. Retrying unchanged will produce the same result.

Why doesn't my client-side schema catch it?

Schemas validate shape and type, but many 422 rules are cross-field, referential, or state-dependent and can only be enforced by the server with access to the full system state.

This is part of the The API Debugging Guide — start there for a systematic way to read status codes and isolate failures.