422 Unprocessable Content

What 422 Unprocessable Content means

422 Unprocessable Content (formerly Unprocessable Entity) is the validation-error code. The request was syntactically valid (parseable JSON, all required fields present), but failed business-rule validation: email already exists, age must be positive, cross-field constraint violated. Many APIs use 400 for everything client-side wrong, but 422 is more specific and lets clients distinguish "your JSON is broken" (400) from "your data is logically invalid" (422).

When servers should return it: Return 422 when the request parsed successfully but failed validation. Include detailed per-field errors in the response body.

Common causes

• Required field has an invalid value
• Cross-field validation failed (start_date > end_date)
• Unique constraint violation (email already taken)
• Foreign key constraint (referenced user does not exist)
• Business rule violated (cannot transition from state A to state C)

How to fix 422 Unprocessable Content

• Read the response body, 422 should always include per-field error details
• Fix the offending fields and retry
• For cross-field errors, may need to re-fetch related resources

Example response

curl -i -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","age":-5}'

HTTP/2 422
content-type: application/json
{
  "error":"validation failed",
  "details":[
    {"field":"email","reason":"already taken"},
    {"field":"age","reason":"must be positive"}
  ]
}

Related status codes

More references

For a one-page reference of all HTTP status codes, see the HTTP cheat sheet. For testing API responses, try the API Tester tool. For inspecting responses on the command line, the curl cheat sheet covers the most common flags.