422 Unprocessable Content: what it means and how to fix it
A 422 means the server understood your request but the data failed validation. How it differs from 400, how to read the error body, and how to return useful 422s from your API.
· 6 min read · By the Spot Downtime team
422 Unprocessable Content means the server understood the request, including its content type and syntax, but could not act on the data inside it. The JSON parsed fine. A value in it did not pass the server's rules.
The code was called "Unprocessable Entity" for years, and you will still see that name in older docs and frameworks. The status code, 422, is the same.
422 vs 400
Both are client errors, and APIs are not consistent about which they use. The usual split is:
- 400 Bad Request: the request itself is broken. Malformed JSON, a missing header, a truncated body, an invalid URL.
- 422: the request is well formed, but the values are wrong. An email without an
@, a quantity of -3, a date in the past, a name that already exists.
Some frameworks use 400 for everything. Others, such as FastAPI and Rails, use 422 for validation failures. Either way, the fix on the client side is the same: read the response body.
Common causes
- Missing or empty required fields. The field is absent,
nullor an empty string. - Wrong type or format. A number sent as a string, an invalid date format, a malformed email or URL.
- Values out of range. Too long, too short, negative, or not one of the allowed options.
- Business rule violations. A duplicate username, an order for an out-of-stock item, a state change that is not allowed from the current state.
- Wrong shape. Fields nested at the wrong level, or wrapped in an envelope the API does not expect, such as
{"user": {...}}versus a flat object. - Stale client code. The API added a required field or tightened a rule and your integration was not updated.
How to diagnose a 422 as a client
1. Read the response body
Unlike a bare 500, a 422 almost always explains itself. Print the full body, not just the status:
curl -i -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d '{"email":"not-an-email","age":-1}'A typical response lists each problem:
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 0 or greater" }
]
}The format varies by API. Some use JSON Pointer paths, some use a flat map of field to messages, and some follow application/problem+json from RFC 9457. Learn your API's shape and surface those messages to your users instead of showing a generic failure.
2. Compare against the documentation or schema
If the API publishes an OpenAPI or JSON Schema file, validate your payload against it before sending. Check types first, then required fields, then enum values.
3. Check the exact bytes you sent
Bugs in serialization produce odd 422s: a number turned into "42", a date formatted in the local locale, a field renamed by a JSON library from userId to user_id. Log the actual request body and compare it with a payload that works.
4. Watch for state-dependent rules
If the same payload works once and then returns 422, the rule is about state: a unique constraint, an idempotency key reuse, or a resource that moved to a status that no longer allows the action.
How to return good 422s from your API
If you build the API, the message is the product. A client developer will only fix what the response tells them about.
- Return every validation error in one response, not just the first one found.
- Name the field or path for each error, and say what is wrong in plain language.
- Use one error format across all endpoints and document it.
- Keep it consistent: pick 400 or 422 for validation and stick to it.
- Never echo secrets or full internal exception text in the body.
An example of a handler that validates and returns structured errors, in Express:
app.post("/users", (req, res) => {
const errors = [];
const { email, age } = req.body ?? {};
if (typeof email !== "string" || !email.includes("@")) {
errors.push({ field: "email", message: "must be a valid email address" });
}
if (!Number.isInteger(age) || age < 0) {
errors.push({ field: "age", message: "must be a whole number, 0 or greater" });
}
if (errors.length > 0) {
return res.status(422).json({ errors });
}
// ...create the user
res.status(201).json({ ok: true });
});Malformed JSON should be rejected earlier, by your body parser, with a 400. Only requests that parse reach the validation step.
Don't retry a 422
A 422 will not succeed by trying again. The same data will fail the same way. Retry logic should cover 5xx errors and 429 with backoff, and treat 4xx validation errors as final. If your client retries 422s, you are only adding load.
Monitoring and 422
A monitor that sends a valid request should never see a 422. If one starts to, something changed: a new required field, a tighter rule or a changed schema. That makes 422 a useful signal for API checks that send a realistic payload. With Spot Downtime's API monitoring you can send a custom request and check the response, so a contract change shows up as a failed check rather than as customer reports. Chained requests are covered in multi-step API checks.
- Read the response body for field-level messages.
- Compare your payload to the API schema and fix types, required fields and values.
- Check the bytes actually sent, not what you meant to send.
- As an API author, return all errors at once, in one documented format.
- Do not retry. Fix the data.
Get new guides by email
Practical posts on monitoring, outages, error fixes and on-call, when they're published. No spam.
Keep reading
- HTTP errors · APIs428 Precondition Required: why the API wants If-Match and how to send itA 428 means the server refuses unconditional writes and requires headers like If-Match. How to read the ETag, send the condition and handle 412 in your client.November 15, 2026 · 6 min read
- HTTP errors · APIs412 Precondition Failed: If-Match, ETags and lost updatesA 412 means a conditional header such as If-Match or If-Unmodified-Since didn't hold. Why it happens, how to fix it in clients and servers, and how it differs from 409.November 14, 2026 · 7 min read