Unprocessable Entity

ⓘ Quick Definition

The HTTP 422 Unprocessable Entity status code means the server understands the content type of the request and the syntax of the request body is correct, but it was unable to process the contained instructions. This typically indicates that the request data failed validation - the structure is correct but the values are semantically invalid.

⏰ When It Occurs

A 422 error occurs when the server can parse your request body (it is syntactically correct), but the data within it fails business logic or validation rules. For example, submitting a user registration form with an email that is missing the @ symbol, a password that is too short, or a birth date set in the future.

This status code originated from WebDAV (RFC 4918 - Web Distributed Authoring and Versioning) and was later adopted broadly by REST APIs. It has since been included in RFC 9110 (HTTP Semantics), making it an official part of the HTTP standard. Modern frameworks like Laravel, Ruby on Rails, and Phoenix use 422 as their default response for validation failures.

⚠ Common Causes

• Missing required fields - Submitting a form or API request without fields the server requires (e.g., no email on signup)
• Invalid field format - Providing data in the wrong format, such as a non-email string in an email field or text in a numeric field
• Value out of range - A quantity of -1, an age of 500, or a date that is in the past for a future-only field
• Business logic violations - Trying to book an already-reserved time slot, transferring more money than the account balance, or creating a duplicate username
• Referencing non-existent resources - Setting a foreign key or relationship to an ID that does not exist in the database
• Conflicting field values - A start date that is after the end date, or a minimum price higher than the maximum price

Framework-Specific Behavior:

Laravel Returns 422 by default for validation errors. The response includes a JSON object with "errors" mapping field names to arrays of error messages. Uses $request->validate() or Form Requests.

Rails ActiveRecord validation failures return 422. render json: @model.errors, status: :unprocessable_entity is the standard pattern. Rails 7+ also uses 422 for Turbo form submissions.

Express No built-in validation. Libraries like express-validator or joi handle validation, and you return 422 manually: res.status(422).json({ errors }).

Django Django REST Framework returns 400 by default for validation errors, but many developers override this to return 422 for semantic consistency. Use raise ValidationError() with a custom exception handler.

🛠 How to Fix

1. Read the error response body - Most APIs return specific validation messages explaining which fields failed and why
2. Check all required fields - Ensure every required field is present, non-null, and not an empty string
3. Validate field formats - Verify emails contain @, dates are in the correct format (ISO 8601), and numbers are actually numeric
4. Check value constraints - Ensure values fall within acceptable ranges (min/max length, numeric bounds, allowed enum values)
5. Verify business logic - Check for duplicate entries, valid references, and logical consistency between related fields
6. Review API documentation - Consult the API docs for the exact validation rules, required fields, and expected formats for each endpoint

💻 HTTP Example

# Client submits a user registration with invalid data
POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "",
  "email": "not-an-email",
  "password": "123",
  "age": -5
}

# Server Response (validation failed)
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "message": "The given data was invalid.",
  "errors": {
    "name": ["The name field is required."],
    "email": ["The email must be a valid email address."],
    "password": ["The password must be at least 8 characters."],
    "age": ["The age must be a positive number."]
  },
  "statusCode": 422
}

🔗 Related Status Codes