Status Codes That Actually Communicate
You'll learn to
- -Read the first digit of a status code as an instruction to the client: done, fix it, or try later
- -Pick 409 Conflict or 422 Unprocessable Entity correctly, and know how they differ from 400
- -Never hide a client mistake behind a 500
Tip: the highlighter is on - just select any text below to mark it. Use the highlighter button up top to change color or turn it off. Highlights are saved on this device only. Log in to save them to your account instead.
An HTTP status code is a three-digit number that summarizes what happened to a request. A well-designed API lets a client react correctly from the number alone, without reading the body. A retry loop can simply check "is this a 5xx?" and know a retry may be worth trying, without understanding the API's own error format.
An Analogy: A Waiter's Replies
Picture three replies from a waiter. "Coming right up" means all is well (2xx). "We do not serve that, and you left the side dish off your order" means you must change your order (4xx). "The kitchen has a problem, give us a few minutes" means your order was fine and a retry may work (5xx). The first digit tells you what to do next.
The Taxonomy That Matters
- -2xx, success: the request was understood and processed. 200 OK, 201 Created, 204 No Content.
- -4xx, client error: something about the request itself is wrong. The client must fix it, because sending it again unchanged will fail again.
- -5xx, server error: the server failed on an otherwise valid request. The request may have been fine, and a retry, usually with a growing delay, 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 for a request that is well formed and individually valid, but clashes with the current state of the server. Examples are a duplicate email, a version mismatch on an update, or deleting something another record still depends on. This is a different failure from "the data itself is invalid", which is what 422 is for.
422 Unprocessable Entity: Valid Syntax, Invalid Meaning
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"}
]}400 Bad Request is for a request that cannot be parsed at all: malformed JSON, or a required field missing from the shape. 422 is for a request that parses fine but fails rules about the values, such as a bad email format or a negative age. Many APIs use 400 for both, which is defensible. The real signal is knowing the difference and being able to justify your choice.
The demo puts the codes to work. A tiny create_user returns 201, 409, 422 or 400, and a second function tells a client what to do next from the code alone.
A common mistake is returning 500 for what is really a client mistake, such as bad input that crashed unhandled validation code. If the root cause is the client's input, the right code is 4xx, even if the symptom looked like a server 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.
Discussion0
Join the Discussion
Sign in to leave comments, reply to others, or like insights.
No comments yet. Be the first to start the thread!