A request to your API is syntactically valid JSON but fails a business rule — for example an end date before the start date. Would you answer with HTTP status 400 or 422, and how do you draw the line between them in a contract?

## Two different failures When a client sends something wrong, there are two distinguishable situations: 1. **The server cannot interpret the request.** The JSON does not parse; a field declared as an integer contains `"abc"`; a required field is missing so no domain object can be constructed. Nothing about the business is involved — the request never becomes meaningful data. 2. **The server understood the request perfectly and refuses it.** All types check out, the object was constructed, and then a rule said no: the date range is inverted, the discount exceeds the order total, the account is closed so it cannot be charged. `400 Bad Request` covers the first. `422 Unprocessable Content` (renamed from "Unprocessable Entity" in RFC 9110, originally from WebDAV) was defined exactly for the second: the request is well-formed and the content type is understood, but the instructions cannot be followed. ## Where the line actually falls The boundary is fuzzier than it looks, and that is why teams disagree. - *Missing required field* — usually 400 (the object cannot be built), but if your validation layer builds the object and then checks presence, 422 is equally arguable. - *Wrong enum value* — 400 if you treat it as a type error, 422 if you treat it as a domain rule. - *Field too long* — length is a constraint on meaning, so 422 fits, but frameworks commonly emit 400. Because of this, the pragmatic rule is: **pick a policy and enforce it in one place.** Two policies work well. **Policy A (two codes).** 400 for parse/bind failures, 422 for validation failures. This is what many framework defaults naturally produce once a validation library is wired in, and it gives operators a useful split: 400 spikes mean a client is sending garbage (often a deploy or a serialization bug), 422 spikes mean users are hitting a rule. **Policy B (one code).** 400 for all client-side input problems, with the body carrying the detail. Simpler to explain, and honest about the fact that most clients do not branch on the code. Note that 422 is not a wire-level oddity — it is a normal status and any HTTP client handles it — so the argument against it is convention, not compatibility. What is genuinely wrong is having no policy: the same class of failure returning 400 from one service and 422 from another makes error handling in an aggregating client miserable. ## The body is the real contract A status code is one integer; clients need more. Use a structured error format — RFC 9457 Problem Details (`application/problem+json`) is the standard one: ``` HTTP/1.1 422 Unprocessable Content Content-Type: application/problem+json { "type": "https://example.com/probs/validation", "title": "Validation failed", "status": 422, "code": "DATE_RANGE_INVALID", "errors": [ {"field": "endDate", "code": "BEFORE_START", "message": "endDate must be after startDate"} ] } ``` Key properties: a **stable machine code** clients can branch on (never the human message — that gets reworded and translated), **field-level detail** so a UI can highlight inputs, and **all failures at once** rather than one per round trip. Avoid leaking internals: no stack traces, no SQL, no "user 4711 not found in table users". ## Related codes that get confused with these - **415 Unsupported Media Type** — the `Content-Type` itself is one you do not accept (client sent XML, you take JSON). Not 400. - **413 Content Too Large** — body exceeds your limit. Not 400 or 422. - **409 Conflict** — the request is valid but conflicts with current state (duplicate unique key, concurrent modification). The distinction from 422 is whether the problem is *inherent to the request* (422) or *relative to current state* (409). - **404** — the addressed resource does not exist, as opposed to a field inside the body being wrong. ## Operational angle Because 4xx means "the client can fix this", these codes should generally **not** page anyone and should **not** be retried by the client. Make sure your dashboards separate 4xx from 5xx, and watch for the inversion where a server bug is reported as 400 — that hides real outages behind a "client error" label, and it is one of the more common ways an incident goes unnoticed for hours.