HTTP 422 Unprocessable Content indicates that a server understood the request content type and the content’s syntax, but could not process its instructions. It is useful for semantic validation failures in APIs, such as a well-formed document containing values that do not satisfy the endpoint’s contract.
The status should help clients decide what to do next. Repeating the same invalid request generally produces the same failure. A useful response therefore explains the correctable problem without exposing internal implementation details or private resource information.
Separate syntax, meaning, and state
A request can fail at several layers. Invalid JSON syntax, an unsupported content type, a semantically invalid value, and a conflict with current resource state are different conditions.
Choose statuses consistently with the API’s established contract and relevant HTTP semantics. A 422 response should not become a catch-all for every exception that happened after parsing. An unavailable database or an unexpected application error is not a client validation failure.
Document examples for common boundaries. A valid JSON document with an impossible date can fit semantic validation. A request referring to an outdated resource version may fit the API’s conflict or precondition policy instead. Consistency helps clients build predictable error handling.
HTTP 422 Unprocessable Content needs a stable body
An illustrative response might use a machine-readable code and field detail:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json
Cache-Control: no-store
{
"error": "validation_failed",
"fields": [
{"path": "quantity", "code": "out_of_range",
"message": "Quantity must be between 1 and 100."}
]
}The quantity rule and error schema are examples, not universal standards. Use the application’s documented error format and make the actual HTTP status match the body. A status of 200 with an error-looking JSON object confuses generic clients and monitoring.
Keep machine codes stable even when human wording changes or is translated. Clients should not have to parse English sentences to decide which field needs correction.
Validate values with a clear contract
Semantic validation should describe the accepted type, range, format, and cross-field relationships. A field containing the string “12” may be invalid where a JSON number is required even though a human can interpret it.
Decide whether normalization happens before validation. Trimming whitespace, changing case, or converting a local date can alter meaning. Document these behaviors so clients know which exact value the server processes.
For cross-field errors, identify the relationship rather than blaming one arbitrary field. An end date earlier than a start date concerns both values. A useful error can explain the invariant and point to the relevant locations.
Do not let implementation-specific parser behavior define the business contract accidentally. Centralize shared validation rules where appropriate, and test that all write paths enforce them consistently.
Keep validation separate from authorization
A well-formed request is not necessarily permitted. Authenticate and authorize the requested action under the application’s policy rather than treating successful field validation as access approval.
Error detail can also leak information. A message explaining that an email address belongs to another account or that a private record was deleted may reveal facts the caller is not entitled to learn.
Return only the detail appropriate to the caller’s access level. Keep richer diagnostic information in protected server evidence, linked by a non-sensitive correlation identifier when useful. Avoid exposing database constraint names, stack traces, or internal paths as ordinary validation messages.
Do not echo passwords, tokens, or sensitive submitted values in the response. A field location and an actionable rule are usually enough to support correction.
Decide whether partial success is allowed
For a multi-field resource update, specify whether validation failure means no change occurred. Clients need to know whether correcting one field and resubmitting might repeat an already applied side effect.
Prefer an atomic contract where the operation logically belongs together. Validate before committing, and ensure late database constraints or concurrent state changes cannot leave an unexplained partial result.
Batch APIs may support per-item results, but that is a distinct contract. Report which items succeeded and failed through the documented structure instead of using one ambiguous 422 response to hide a mixture of outcomes.
Avoid stating “nothing changed” unless the implementation actually guarantees it. A response code does not by itself establish transaction boundaries or rollback behavior across external services.
Clients should correct, not blindly retry
A 422 response normally requires changing the request or resolving the documented validation condition. An automatic retry loop with identical content wastes capacity and can bury the useful error under repeated failures.
Map field errors back to the submitted form or object. Preserve the user’s input safely, highlight relevant fields, and provide guidance that matches the server’s actual rule. Do not erase the whole form because one value failed.
Separate transport retries from validation handling. If a client library retries every non-success response indiscriminately, configure it to recognize terminal client errors under the API’s contract. Also test whether a proxy or gateway preserves the status and body.
For asynchronous workflows, record the validation result in the work item’s lifecycle rather than repeatedly requeueing an unmodified invalid payload. Give an authorized user a clear correction path.
Bound error collection and disclosure
Returning every validation error can help a user fix several fields at once. However, unbounded error lists can consume resources or expose a large amount of submitted content.
Set reasonable limits on request size, field counts, and reported errors. Keep field paths structurally safe and render messages as text in browser clients. An error message should not become an injection path in the UI that displays it.
Apply suitable cache behavior when responses contain user-specific or sensitive details. The example uses no-store, but the exact policy belongs to the application’s data classification and architecture.
Test the complete failure path
Include valid syntax with invalid values, wrong JSON types, cross-field conflicts, unknown fields, and an authorized valid request. Test malformed syntax and unsupported media types separately so they do not silently receive the semantic-error response.
Verify the actual public status, content type, stable machine codes, and permitted detail. Test localized messages and confirm clients still use codes rather than translated text for logic.
Add a concurrent-state test where input passed initial validation but the database rejects the final write. Confirm that the API returns a truthful error and preserves its atomicity promise.
Frequently asked questions
Is 422 the right code for any failed POST?
No. The failure’s layer and the API contract matter. Authentication failures, conflicts, unsupported media, and service errors need separate interpretation.
Should the client resend the same body?
Not as a routine recovery strategy. MDN notes that repeating the request without modification should be expected to fail again.
Can a helpful error expose too much?
Yes. Explain correctable rules without revealing private records, secrets, or internal implementation details.
Practical takeaway
Use 422 for a clearly defined semantic validation failure. Pair it with stable codes, actionable field guidance, truthful atomicity, and privacy-aware detail. The best validation response makes correction easier without teaching clients to retry the impossible.
Documentation and related reading
Check the official documentation for the exact behavior of your deployed version. For complementary implementation guidance, read the API object-level authorization guide.
