422
Client Error
422 Unprocessable Entity: Semantic Validation Errors
✦ The Golden Answer: The 422 Unprocessable Entity status code indicates that the server understands the request's content type and the syntax is correct, but it cannot process the contained instructions due to semantic errors. This is the go‑to status for validation failures in REST APIs — for example, when a required field is missing, an email is malformed, a value is out of range, or a business rule is violated (e.g., "the product is out of stock"). Unlike 400, which is used for malformed syntax, 422 is for well‑formed but invalid data.
Common Causes of 422 Errors
| Cause | Example | How to Fix |
|---|---|---|
| Missing required field | POST /users without email field. | Include all required fields in the request. |
| Invalid data format | Field expects integer but receives string. | Correct the data type. |
| Value out of range | Age field expects 18–99, but client sends 150. | Validate input on client side before sending. |
| Duplicate unique constraint | Email already exists in the database. | Use a different email or update the existing record. |
| Business rule violation | Order cannot be placed because product is out of stock. | Check availability before ordering. |
| Invalid enum value | status must be 'active' or 'inactive', client sends 'pending'. | Send a valid enum value. |
Example: 422 Response
A client attempts to create a user with an invalid email format:
POST /api/users HTTP/1.1
Host: example.com
Content-Type: application/json
{"name": "John", "email": "not-an-email"}
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"errors": {
"email": ["must be a valid email address"]
}
}
422 vs. Other 4xx Codes
| Status | Meaning | When to Use |
|---|---|---|
| 400 Bad Request | Malformed syntax (invalid JSON, missing headers). | Cannot parse the request. |
| 422 Unprocessable Entity | Valid syntax, but semantic errors. | Validation failures, business rule violations. |
| 409 Conflict | Conflict with current state (e.g., optimistic locking). | State conflict, not validation. |
| 415 Unsupported Media Type | Wrong Content-Type. | Content-Type not supported. |
How to Fix 422 Errors
- If you're a client developer: Validate your request data before sending it. Check the API documentation for required fields, data types, and allowed values. Use the error response to identify which fields are invalid and correct them.
- If you're a server developer: Implement proper validation for all incoming requests. Return clear and structured error messages (e.g., JSON with field‑specific errors) so clients can easily fix their requests.
- If you're an end‑user: This error usually means you submitted a form with invalid data (e.g., missing fields, wrong format). Check the error message and correct your input.
Best Practices for 422
- Always provide context – include a detailed error message explaining what went wrong and which fields are invalid.
- Use consistent error format – e.g.,
{"errors": {"field": ["message1", "message2"]}}. - Don't use 422 for authentication – that's 401 (unauthorized) or 403 (forbidden).
- Use 400 for syntax errors – reserve 422 for semantic validation.
Frequently Asked Questions
Is 422 a client error or a server error?
It's a client error (4xx) because the client's request contains invalid data that the server cannot process. The server is working correctly but refuses to accept the payload due to validation rules.
Should I use 422 or 400 for validation errors?
Many APIs use 400 for all client errors, but the HTTP specification recommends 400 for malformed syntax and 422 for well‑formed but invalid data. Using 422 is more precise and helps clients distinguish between different types of errors.
Is 422 part of the original HTTP/1.1 specification?
No, 422 was introduced in WebDAV (RFC 4918) and later adopted by REST APIs. It is now widely used in JSON APIs (e.g., JSON:API, GraphQL) for validation errors.