EC
422
HTTPERRORNotable4xx Client ErrorHIGH confidence

Unprocessable Entity

Production Risk

Low. It is very useful for providing clear, actionable feedback to API clients about why their validly-formed request could not be processed.

What this means

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 is a semantic error, not a syntax error.

Why it happens
  1. 1A client sends JSON with all the correct fields, but the values are logically incorrect (e.g., an end date that is before a start date).
  2. 2A user tries to register with a username that is syntactically valid but fails business rule validation (e.g., contains a reserved word).
  3. 3The request contains semantic errors that prevent the server from processing it.
How to reproduce

A user submits a form to create an event with a start date of '2023-01-10' and an end date of '2023-01-05'.

trigger — this will error
trigger — this will error
POST /api/events HTTP/1.1
Host: example.com
Content-Type: application/json

{ "name": "My Event", "start": "2023-01-10", "end": "2023-01-05" }

expected output

HTTP/1.1 422 Unprocessable Entity

Fix 1

Provide a Detailed Error Body

WHEN You are the server rejecting a request.

Provide a Detailed Error Body
{
  "errors": [
    { "field": "end_date", "message": "End date cannot be before the start date." }
  ]
}

Why this works

Server-Side Response

Fix 2

Correct the Semantic Error

WHEN You are the client.

Correct the Semantic Error
Read the error message from the server and correct the invalid data before resubmitting.

Why this works

Client-Side Correction

What not to do

✕

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All HTTP errors