HTTP 422 Unprocessable Entity — Semantic Validation vs 400

When to Return 422

Use 422 for business-logic validation failures distinct from format errors: a valid JSON body where the values fail domain rules (e.g., start date after end date, negative price). Use 400 for structural/format errors.

Common Causes

• Start date is after end date
• Requested quantity exceeds available stock
• Age below minimum required (must be 18+)
• Password does not meet complexity requirements
• Circular reference in hierarchical data

HTTP Response Example

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

{"error": "Unprocessable Entity", "message": "startDate must be before endDate"}

Code Examples

app.post('/bookings', async (req, res) => {
  const { startDate, endDate, roomId } = req.body

  // Structural validation (400)
  if (!startDate || !endDate) {
    return res.status(400).json({ error: 'startDate and endDate are required' })
  }

  // Semantic validation (422)
  if (new Date(startDate) >= new Date(endDate)) {
    return res.status(422).json({
      error: 'Unprocessable Entity',
      message: 'startDate must be before endDate',
    })
  }
  // proceed
})

export async function POST(request: Request) {
  const { startDate, endDate } = await request.json()
  if (new Date(startDate) >= new Date(endDate)) {
    return Response.json(
      { error: 'Unprocessable Entity', message: 'startDate must be before endDate' },
      { status: 422 }
    )
  }
}

Related Status Codes