422 Unprocessable Entity

Description

The 422 Unprocessable Entity status code indicates that the server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions. This status code is often used when validation errors prevent the request from being processed.

This status code is commonly used when: - The request data is syntactically correct (e.g., well-formed JSON or XML) but semantically invalid - Input validation fails for submitted data - The request contains logical errors that prevent processing - Business rules or constraints are violated by the request data

The 422 Unprocessable Entity status differs from 400 Bad Request in that the request syntax is correct, but the contained data has semantic errors or cannot be processed due to business logic constraints.

Syntax

The server responds with a 422 Unprocessable Entity status:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Content-Length: [length in bytes]

{
  "error": "Unprocessable Entity",
  "message": "The request was well-formed but contains semantic errors",
  "details": [specific validation errors or issues]
}

Examples

Form Validation Example

A client submits a form with semantically invalid data:

Client Request:

POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Content-Length: 98

{
  "username": "john.doe",
  "email": "not-a-valid-email",
  "password": "short"
}

Server Response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Content-Length: 243

{
  "error": "Unprocessable Entity",
  "message": "Validation failed",
  "errors": {
    "email": "Must be a valid email address",
    "password": "Must be at least 8 characters long and contain at least one number"
  }
}

Business Logic Constraint Example

A client attempts to create a resource that violates business rules:

Client Request:

POST /api/appointments HTTP/1.1
Host: booking.example.com
Content-Type: application/json
Content-Length: 145
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "service_id": 123,
  "date": "2023-06-15",
  "time": "14:30",
  "duration": 60,
  "customer_id": 456
}

Server Response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Content-Length: 215

{
  "error": "Unprocessable Entity",
  "message": "Cannot create appointment",
  "errors": {
    "time": "The requested time slot is already booked",
    "date": "Appointments must be scheduled at least 24 hours in advance"
  }
}

Data Relationship Example

A client submits data with invalid relationships:

Client Request:

POST /api/orders HTTP/1.1
Host: shop.example.com
Content-Type: application/json
Content-Length: 187
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "customer_id": 789,
  "items": [
    {"product_id": 123, "quantity": 2},
    {"product_id": 456, "quantity": 1},
    {"product_id": 999, "quantity": 3}
  ],
  "shipping_address_id": 42
}

Server Response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Content-Length: 287

{
  "error": "Unprocessable Entity",
  "message": "Order cannot be processed",
  "errors": {
    "items[2].product_id": "Product with ID 999 does not exist",
    "shipping_address_id": "Address with ID 42 does not belong to customer with ID 789",
    "items[1].quantity": "Product with ID 456 only has 0 items in stock"
  }
}

Summary

The 422 Unprocessable Entity status code is a valuable tool for API design, providing a clear distinction between syntactic errors (which would result in a 400 Bad Request) and semantic or business logic errors. By using this status code, servers can provide detailed feedback about validation issues, constraint violations, and other semantic problems with otherwise well-formed requests. This helps developers quickly identify and fix issues with their API requests, improving the overall developer experience and reducing debugging time.