Status Codes That Actually Communicate
You'll learn to
- -Apply the 2xx/4xx/5xx taxonomy correctly, including the less-common but important 409 and 422
- -Distinguish a client error (4xx) from a server error (5xx) precisely, since the distinction drives how a client should react
HTTP status codes are a machine-readable summary of what happened, and a well-designed API lets clients react correctly without ever parsing the response body - a retry loop can check "is this 5xx" and know it might be worth retrying, without needing to understand the API's specific error format.
The Taxonomy That Matters
- -2xx (Success): the request was understood and processed correctly. 200 OK, 201 Created, 204 No Content.
- -4xx (Client Error): something about the request itself was wrong - the client should fix the request before retrying as-is. Retrying an unchanged 4xx request will fail again.
- -5xx (Server Error): the server failed to process an otherwise-valid request - the client's request may have been fine, and retrying (often with backoff) can be reasonable.
409 Conflict: State, Not Syntax
POST /users
{"email": "ada@example.com", "name": "Ada Lovelace"}
HTTP/1.1 409 Conflict
{"error": "A user with this email already exists"}409 is specifically for when the request is well-formed and the data is individually valid, but conflicts with the current state of the server - a duplicate email, a version mismatch on an optimistic-concurrency update, trying to delete a resource that something else still depends on. This is a different failure mode from "the data itself fails validation" (wrong format, out of range), which is what 422 is for.
422 Unprocessable Entity: Valid Syntax, Invalid Semantics
POST /users
{"email": "not-an-email", "age": -5}
HTTP/1.1 422 Unprocessable Entity
{"errors": [
{"field": "email", "message": "must be a valid email address"},
{"field": "age", "message": "must be a positive number"}
]}The distinction between 400 (Bad Request) and 422 is subtle but worth knowing: 400 is for a request that fails to parse at all (malformed JSON, a required field entirely missing from the shape), while 422 is for a request that parses fine but fails validation rules on the values themselves (an invalid email format, a negative age). Many APIs use 400 for both, which is defensible, but knowing the distinction exists - and being able to justify whichever choice you make - is the actual interview signal.
A common mistake: returning 500 Internal Server Error for what is actually a client mistake (bad input that crashed unhandled validation logic). If the root cause is invalid client input, the correct code is 4xx even if the immediate symptom looked like a server-side exception - fix the handling, not just the status code.
A user tries to book the last seat on a flight, but another request books it a moment earlier. What status code fits, and why?
"500, since something went wrong on the server."
"409 Conflict - the request itself was perfectly valid, but it conflicts with the current state: the seat that was available when the client checked is no longer available now. That's exactly what 409 is for, as opposed to 422 (which would mean something about the request data itself was invalid) or 500 (which would imply an actual server-side failure, not a legitimate state conflict)."
What is the key difference between a 4xx and a 5xx status code?
Design Status Code Symphony in the API Design Lab's REST Foundations act.