Why Your API Should Return 422 Not 400
Not all client errors are created equal. A malformed JSON payload is fundamentally different from a syntactically valid request that fails business rules. Using 422 Unprocessable Entity instead of 400 Bad Request gives clients precise, actionable feedback and keeps your API semantically correct. This guide explains the HTTP spec reasoning, real-world examples, and when to use each status code.
The HTTP Status Code Definition
| Code | Name | Meaning |
|---|---|---|
| 400 | Bad Request | Generic client error. Malformed syntax, invalid framing, or deceptive request routing. |
| 422 | Unprocessable Entity | Well-formed request but semantically invalid. Validation failed on server-side constraints. |
| 409 | Conflict | Request conflicts with current resource state. |
| 404 | Not Found | Resource does not exist. |
Why 400 Is Too Broad
400 Bad Request is a catch-all. It tells the client something went wrong, but not what. Returning 400 for every validation failure loses critical context.
| Scenario | 400 Says | 422 Says |
|---|---|---|
| Missing required field | "Bad request" | "Field 'email' is required" |
| Invalid email format | "Bad request" | "'email' must be a valid email address" |
| Password too short | "Bad request" | "'password' must be at least 8 characters" |
| Wrong enum value | "Bad request" | "'status' must be one of: active, inactive" |
The Semantic Difference
HTTP 422 was introduced in RFC 4918 (WebDAV) and carries a specific meaning: the server understands the content type and syntax of the request, but the instructions contain semantically erroneous instructions.
| Aspect | 400 Bad Request | 422 Unprocessable Entity |
|---|---|---|
| Syntax | Malformed or invalid | Well-formed and valid |
| Semantics | N/A | Semantically invalid |
| Validation | Syntax-level | Business-rule level |
| Fixability | Often unclear | Specific field errors |
| Client action | Retry or debug | Correct specific fields |
Related Keywords
Developers and API designers also search for:
- 422 vs 400 — when to use each HTTP status code
- 422 unprocessable entity — REST API validation errors
- HTTP 422 status code — meaning and usage guide
- 400 bad request vs 422 — API error handling best practices
- REST API validation errors — proper HTTP status codes
- 422 status code example — real API response samples
- when to use 422 — API design guidelines
- 422 vs 409 — conflict vs validation errors
- REST API error responses — semantic HTTP status codes
- 422 RFC 4918 — WebDAV unprocessable entity specification
Real-World Validation Scenarios
Example 1: User Registration
// 422 Response { "errors": [ { "field": "email", "message": "Must be a valid email" }, { "field": "age", "message": "Must be positive" } ] } ```
Example 2: Order Creation
// 422 Response { "errors": [ { "field": "productId", "message": "Must be a valid UUID" }, { "field": "quantity", "message": "Must be at least 1" } ] } ```
Major API Style Guides
| Organization | Recommendation |
|---|---|
| Google API Design Guide | Use 400 for malformed requests, 422 for semantic errors |
| Microsoft REST Guidelines | Use 400 for protocol errors, 422 for validation |
| JSON API spec | Use 422 for validation failures |
| GraphQL | Returns 200 with errors array, but semantic errors |
| Stripe API | Uses 400 for param errors, 422 for card declines |
| Shopify API | Uses 422 for validation errors |
Error Response Structure
A well-formed 422 response includes machine-readable details.
| Field | Purpose | Example |
|---|---|---|
| code | Machine-readable error code | VALIDATION_ERROR |
| field | The field that failed | |
| message | Human-readable description | Must be a valid email |
| type | Error severity | error |
When 400 Is Correct
| Scenario | Use 400 |
|---|---|
| Malformed JSON | Syntax error, missing quotes |
| Invalid Content-Type | Header missing or wrong |
| Empty request body | No payload when one required |
| Invalid URL encoding | Query string parsing fails |
| Unsupported HTTP method | POST to GET-only endpoint |
When 422 Is Correct
| Scenario | Use 422 |
|---|---|
| Required field missing | Field exists but is null/empty |
| Wrong data type | Number passed instead of string |
| Invalid enum value | Status must be active/inactive |
| String length violation | Min 3, max 50 characters |
| Pattern mismatch | Email, phone, zip format |
| Business rule violation | Can't cancel shipped order |
Other Relevant Status Codes
| Code | When to Use |
|---|---|
| 400 | Malformed request syntax |
| 401 | Missing or invalid authentication |
| 403 | Authenticated but not authorized |
| 404 | Resource not found |
| 409 | Resource state conflict |
| 422 | Semantically invalid request |
| 429 | Rate limit exceeded |
| 500 | Unexpected server error |
Conclusion
Returning 422 Unprocessable Entity instead of 400 Bad Request for validation failures makes your API more precise, self-documenting, and easier to debug. It respects the HTTP semantics, aligns with major API style guides, and gives frontend developers the context they need to build better user experiences. Reserve 400 for truly malformed requests, and use 422 for well-formed requests that fail validation.