422 - Unprocessable Content
HTTP 422 Unprocessable Content means the request syntax is valid but semantic validation fails for supplied instructions.
Last reviewed: March 13, 2026|Editorial standard: source-backed technical guidance
What Does Unprocessable Content Mean?
The request is syntactically valid, but business/domain rules reject the requested action, so processing stops at semantic validation boundaries.
Common Causes
- -JSON payload passes syntax parsing but domain validator rejects endDate earlier than startDate constraint.
- -Business rules disallow provided currency and country pair for merchant profile, producing semantic validation failure.
- -Username matches regex yet violates reserved prefix policy enforced in application-level rule engine.
How to Fix Unprocessable Content
- 1Parse server validation details and map each semantic violation to a specific field or rule.
- 2Correct domain rule conflicts (state transitions, field dependencies, cross-entity constraints) before retry.
- 3Mirror server business validations in client and SDK layers to fail fast earlier.
Step-by-Step Diagnosis for Unprocessable Content
- 1Capture machine-readable validation errors and rule identifiers returned with 422.
- 2Differentiate schema/parsing issues (400/415) from semantic rule failures that belong to 422.
- 3Trace rule-evaluation inputs, including related entity state used by domain validators.
- 4Retest with minimal valid business inputs, then reintroduce optional fields incrementally.
Semantic Rule and Field Dependency Audit
- -Inspect cross-field constraints (example:
startDatemust be earlier thanendDate). - -Validate domain-state prerequisites (example:
status=shippednot allowed 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).
Implementation Examples
curl -i -X POST https://api.example.com/v1/orders -H "Content-Type: application/json" -d "{"startDate":"2026-03-10","endDate":"2026-03-01"}"
# Response:
# HTTP/1.1 422 Unprocessable Content
# {"error":"Unprocessable Content","code":"422"}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) {
console.error('Handle 422 Unprocessable Content');
}import requests
response = requests.post(
'https://api.example.com/v1/orders',
headers={'Accept': 'application/json', 'Content-Type': 'application/json'},
json={'startDate': '2026-03-10', 'endDate': '2026-03-01'}
)
if response.status_code == 422:
print('Handle 422 Unprocessable Content')How to Verify the Fix
- -Resubmit 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.
How to Prevent Recurrence
- -Expose shared validation rules via schema/SDK packages to keep clients and server aligned.
- -Add rule-focused contract tests for business invariants and cross-field dependencies.
- -Version semantic validation rules and communicate breaking behavior changes explicitly.
Pro Tip
- -assign stable validation error codes per rule so clients can localize UI behavior without brittle string parsing.
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.
Playbook
CORS Error Fix Playbook (Preflight / Origin / Credentials)
Use this playbook to separate browser-enforced cross-origin policy failures from server-side CORS header and route defects and apply strict origin and credential controls safely.
Official References
Provider Context
This guidance is specific to HTTP services. Always validate implementation details against official provider documentation before deploying to production.