422 - Unprocessable Content
HTTP 422 Unprocessable Content means the request is structurally valid, but the server rejects its semantic meaning or domain-rule combination.
Last reviewed: April 23, 2026|Source-backed guidance under our editorial policy
Start Here
Use the closest compare guide, playbook, or adjacent error page to narrow the decision faster before you start changing production systems.
This page is part of the Error Reference library. Learn more about the project or report a correction.
What Does Unprocessable Content Mean?
Parsing already succeeded. Content type, syntax, and basic structure were acceptable, but the server refused to process the instructions because they violate semantic validation, business invariants, or domain-level combinations encoded in the request itself.
Common Causes
- -Cross-field constraints fail even though the JSON body is syntactically correct.
- -Business rules reject the requested quantity combination or domain-specific invariant encoded in the payload.
- -Referenced entities are valid individually but incompatible in the same request context.
- -Validation logic rejects the submitted instruction set even though syntax and media type were valid.
- -A shared form or SDK path validates too shallowly and sends semantically invalid but syntactically correct payloads.
How to Fix Unprocessable Content
- 1Read the server validation payload and map each semantic violation to a specific field, rule, or referenced entity.
- 2Separate request-intrinsic semantic failures from live state conflicts before choosing whether this is really 422 or closer to 409.
- 3Correct cross-field, cross-entity, or domain-state rule conflicts before retrying.
- 4Mirror high-value server validations in client and SDK layers so invalid combinations fail earlier.
Step-by-Step Diagnosis for Unprocessable Content
- 1Capture machine-readable validation errors, rule identifiers, and any referenced entity IDs returned with 422.
- 2Differentiate syntax and media-type failures (
400,415) from semantic rule failures that belong to422. - 3Trace rule-evaluation inputs, including referenced entities and policy version used by domain validators.
- 4Retest with a minimal valid business payload, then reintroduce optional or high-risk fields incrementally.
- 5Determine whether the server is rejecting semantic content encoded in the payload or a conflicting live state transition that may belong to
409instead.
Seen in Production
- -A checkout payload is syntactically valid, but
endDateprecedesstartDateand the order validator rejects it with 422. - -An account update references a coupon, tenant, or payment method that exists but is not compatible with the submitted request.
- -A request encodes an invalid business transition, even though the JSON schema passes.
- -A shared form path sends a field combination that passed client regex checks but violates server-side domain rules.
Semantic Rule and Field Dependency Audit
- -Inspect cross-field constraints (example:
startDatemust be earlier thanendDate). - -Validate cross-field semantic prerequisites encoded in the request (example:
status=shippedis invalid whilepaymentStatusispending).
Domain Invariant and Reference Integrity Checks
- -Audit referenced entity compatibility (example: coupon belongs to another tenant, so order update is semantically invalid).
- -Trace rule version drift between services (example: checkout service updated limits but profile service still applies older constraints).
Decision Shortcut: Semantic Validation vs Conflict
- -If the same payload is invalid even after a fresh read, stay on 422.
- -If the problem is a stale version, duplicate intent, or conflicting current state that would change after a fresh read, move toward 409.
- -If parsing or media type fails before business validation begins, inspect 400 or 415 instead.
Wrong Fix to Avoid
- -Do not retry the same semantically invalid payload and expect a different result.
- -Do not collapse all business-rule failures into generic 400 responses if clients need stable semantic diagnostics.
- -Do not patch only frontend validation while leaving the shared backend rule source ambiguous or undocumented.
Implementation Examples
{
"requestId": "req_422_18f4",
"status": 422,
"rule": "date_range_invalid",
"fieldErrors": [
{
"field": "endDate",
"message": "must be after startDate"
}
]
}const response = await fetch('https://api.example.com/v1/orders', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
body: JSON.stringify({ startDate: '2026-03-10', endDate: '2026-03-01' })
});
if (response.status === 422) {
const problem = await response.json();
console.error(problem.rule, problem.fieldErrors);
}rg 'status=422|date_range_invalid|invalid_transition|incompatible_reference' application.logIncident Timeline
15:22 UTC
A client sends a syntactically valid but semantically invalid request
Signal: The payload clears parsing and media-type checks but violates business rules or cross-field semantic constraints.
Why it matters: The first useful question is which semantic rule failed, not whether the JSON parsed correctly.
15:23 UTC
The server rejects the request with 422
Signal: Validation logic stops processing and returns field or rule-level diagnostics.
Why it matters: This is a semantic-content failure, not a transport, syntax, or availability problem.
15:25 UTC
Blind retries preserve the same invalid instruction set
Signal: Clients resend the same payload and trigger the same rule failure repeatedly.
Why it matters: Retry volume obscures the real issue because the request meaning did not change.
15:32 UTC
The invalid combination is corrected and processing resumes
Signal: The caller supplies a valid field combination or domain-compatible reference and the endpoint accepts the request.
Why it matters: That confirms the root cause lived in semantic validation rather than parser failure or a live-state conflict.
Seen in Production
Booking request violates temporal business rule
Frequency: common
Example: Client submits endDate earlier than startDate; payload parses correctly but fails domain validation.
Fix: Apply cross-field validation in client forms and API gateway prechecks before submission.
Referenced entity is valid but incompatible in current domain context
Frequency: medium
Example: Promotion code belongs to another tenant, so checkout update is semantically rejected with 422.
Fix: Validate reference compatibility before submission and surface tenant or context mismatch clearly.
Rule-version drift between microservices
Frequency: rare
Example: Checkout service enforces a new credit limit while the mobile app still validates against the old threshold, causing 422 only in production.
Fix: Centralize rule definitions and publish versioned validation contracts consumed by all clients.
Wrong Fix vs Better Fix
Retry same payload vs fix the rule violation
Wrong fix: Replay the same request because syntax looked valid and the server might accept it later.
Better fix: Map the validation failure to a specific rule, fix the payload meaning, and replay only the corrected request.
Why this is better: 422 is deterministic until the semantic content changes.
Treat as 400 vs preserve semantic diagnostics
Wrong fix: Collapse every validation problem into one generic bad-request response.
Better fix: Return stable semantic error codes or field-level diagnostics so clients can correct the right rule boundary.
Why this is better: Clients recover better when semantic failures are distinguishable from syntax and media-type errors.
Patch one field blindly vs inspect rule context
Wrong fix: Change one visible field and hope the semantic failure disappears.
Better fix: Inspect cross-field, cross-entity, and workflow constraints before modifying the payload.
Why this is better: Many 422s are caused by combinations, not by one obviously malformed field.
Debugging Tools
- -Structured validation error payload inspection
- -Server access logs with request IDs
- -Contract tests in CI
- -Rule-engine or validator debug logging
How to Verify the Fix
- -Resubmit the corrected payload and confirm semantic validations now pass.
- -Run negative rule tests to ensure invalid domain combinations still return 422 predictably.
- -Confirm validation error payloads remain stable for client-side error handling contracts.
- -Verify adjacent 400 and 409 paths are still classified correctly after validation changes.
How to Prevent Recurrence
- -Expose shared validation rules via schema or SDK packages so clients and server stay aligned.
- -Add rule-focused contract tests for business invariants, cross-field dependencies, and reference compatibility.
- -Version semantic validation rules and communicate breaking behavior changes explicitly.
- -Emit stable rule identifiers per semantic failure so clients do not depend on free-form strings.
Pro Tip
- -record the top 422 rule IDs in telemetry so you can see which business constraints are causing the most production friction.
Decision Support
Compare Guide
HTTP 400 vs 422: Bad Request vs Unprocessable Content
Fix API payload issues faster by using 400 for malformed syntax and 422 for semantic validation failures, so clients correct format before business rules.
Playbook
Validation Failure Playbook (400 / 422 / INVALID_ARGUMENT)
Use this playbook to separate malformed-request failures from semantic validation failures, then fix request contracts without broad server-side bypasses.
Official References
Provider Context
This guidance is specific to HTTP services. Always validate implementation details against official provider documentation before deploying to production.