In the previous lesson we kept dropping numbers along the way: 201 on creation with Location, 204 with no body, 404 versus 410, 409 when the transition is not possible, 415 when the Content-Type is not supported. Each of those codes is a contract decision: it is the first thing a client reads and what determines whether it retries, shows the user an error, follows a redirect or ends the session. Choosing the wrong code makes an otherwise well-designed API indecipherable. This lesson goes through the codes a REST API actually uses —not the complete list in the IANA registry—, builds a decision tree so you always get it right, and designs Aroma Store's error body, comparing it with the standard application/problem+json.

1. The five families and why they matter
2. The 2xx family: success
3. The 3xx family: redirection
4. The 4xx family: client error
5. The 5xx family: server error
6. Aroma Store's master table
7. Decision tree: how to choose the right code
8. The error body: problem+json and Aroma Store's format
9. Catalogue of business error codes
10. Antipatterns

In 01-03 we saw the map; now we go into detail. The first digit of the code classifies the response:

This classification is not decorative: it is logic that real software depends on. A generic HTTP client, a load balancer or a partner's gateway decide based on the first digit alone. If you return 200 for an error, no automatic retry will fire and no alert will go off. If you return 500 because the client mistyped a value, the system will retry a request that will never work, and your on-call team will get a page at three in the morning for a failure that is not theirs.

Of the 1xx family only 100 Continue deserves a mention, and HTTP clients handle it transparently when uploading large bodies. You will not use it explicitly.

Generic success, with a body. It is used by correct GET, PUT and PATCH requests and by action POSTs that do not create a new resource.

Remember from 02-03: a collection GET with no results is 200 with {"data": [], "total": 0}, never 404.

A resource has been created. The Location header is mandatory, carrying its URI.

Location is what lets the client chain operations without building URLs by hand, and it is the minimum of hypermedia every API should provide. In Aroma Store it is returned by POST /orders, POST /coffees, POST /coffees/{id}/reviews, POST /orders/{id}/payment and every action sub-resource.

"I have accepted the request, but I have not processed it yet." It is the code of asynchronous processing, and its contract includes telling the client where to check the progress.

Beware the trap of 202: when you return 202 you are saying that it may fail later, so you need a resource where the client can see the final outcome. A 202 with nowhere to look is a black hole.

Success with no body. The client must not try to parse anything. Uses in Aroma Store: a successful DELETE, PUT/PATCH when the client does not need the representation, and OPTIONS.

Strict rule: 204 means a body of zero length. Returning 204 with JSON inside breaks clients that, quite correctly, do not even read the stream.

A partial response to a request with Range. In Aroma Store it appears in exactly one place: the resumable download of the PDF invoice.

It is not used to paginate JSON: the mechanisms in 02-06 are there for that.

The resource has changed URI for good. Aroma Store uses it to normalise the trailing slash (/coffees/ → /coffees) and for URIs inherited from the old API.

"What you have in your cache is still valid." It answers conditional requests carrying If-None-Match or If-Modified-Since, and it goes without a body, which is precisely the saving.

Conditional caching in full —ETags, Last-Modified, validation, revalidation— is developed in 04-06. Here it is enough to know that 304 is not an error but a very cheap success.

The historical problem: faced with a 301 or a 302, many clients turned a POST into a GET when following the redirect, something the standard never intended but which became established practice. To remove the ambiguity, two codes were created that guarantee the method and the body are preserved:

Aroma Store's decision: 302 is not used under any circumstances. For permanent moves, 301 if only reads are affected and 308 if writes may be affected; for temporary ones, 307.

It is the richest family and the one people get wrong most often. In all of them the body carries the error format from section 8.

The request is malformed or the data is not valid: JSON with a syntax error, a wrong type, a missing mandatory field, an unknown field (remember: Aroma Store is strict on input), an invalid query parameter.

An important design note: all validation errors are returned at once, not just the first one. A form that fails field by field, across successive requests, is torture for the user.

The most misused distinction in the whole HTTP world. The way to remember it:

• 401 = "I do not know who you are". The Authorization header is missing, or the token is invalid or has expired. The response must include WWW-Authenticate. The client can fix it by authenticating.
• 403 = "I know who you are and you cannot do this". The identity is valid, but it lacks permissions. Authenticating again is no use at all.

The name 401 Unauthorized is a historical mistake in the standard: it should have been called Unauthenticated. The practical consequence in the Aroma Store SPA: on a 401 it tries to refresh the token and retries once; on a 403 it shows "you do not have permission" straight away and does not retry.

There is a third case, awkward but important: when an authenticated client requests somebody else's resource (GET /v1/orders/ord_9999, which belongs to another person), responding 403 confirms that the order exists. To avoid that leak, Aroma Store responds 404 for other customers' private resources. It is a deliberate security decision, it is called masking and it is covered in 04-02.

410 is more informative when you know for certain: it tells the client to stop asking for it. It is especially useful when retiring old versions (02-07).

The resource exists, but it does not support that method. The Allow header is mandatory.

Distinguish it from 404: if DELETE /v1/coffees returned 404, the developer would go hunting for a typo in the URL instead of realising that the method is the wrong one.

They get confused because both are about formats, but they point in opposite directions:

• 406 → the server cannot produce what the client asks for in Accept (output).
• 415 → the server does not understand what the client sends in Content-Type (input).

The request is valid but clashes with the resource's current state. It is the business logic code, and in Aroma Store it comes up often:

Other conflicts in the catalogue: order_already_paid, order_already_cancelled, review_already_moderated, operation_in_progress. The rule for telling it apart from 400: if the data is correct and what prevents the operation is the state of the resource, it is 409.

A precondition sent by the client failed, typically If-Match with an old ETag. It is the optimistic concurrency mechanism that prevents the lost update:

ETags and conditional requests are developed in 04-06.

422 (renamed Unprocessable Content in RFC 9110) means: the syntax is correct, I understand the document, but its contents cannot be processed. The canonical example: a perfectly formed JSON asking for a delivery date in the past.

The debate has been open for years and these are the two positions:

Aroma Store's decision: 400 for all input validation errors (syntax, types, mandatory fields, enumerations, ranges), with the field-by-field detail in details. 422 is reserved for one very specific, well-delimited case: the improper reuse of an Idempotency-Key with a different body (02-03), where the request is impeccable but cannot be processed for a reason that is neither about format nor about the resource's state.

What matters is not which of the two positions you choose, but writing it into the style guide and not deviating from it: what breaks clients is the same kind of failure returning 400 on one endpoint and 422 on another.

The request limit has been exceeded. It must be accompanied by Retry-After and, in Aroma Store, by the quota headers:

The policies, windows and throttling algorithms are lesson 04-04.

Here the client has done nothing wrong. Golden rule: never leak internal details —stack traces, SQL queries, file paths, server names— because they are gold dust for an attacker.

The catch-all: an unhandled exception. It must carry a trace identifier so that the client can quote it when raising an incident:

That traceId is the seam between the response and your logs, and it is the foundation of observability (04-07).

503 is the only one that can be planned, and that is why it carries Retry-After, which accepts either seconds or an HTTP date:

Careful with 504: the wait timed out, but the operation may have executed anyway upstream. It is exactly the scenario that justifies the idempotency keys from 02-03.

Walk this tree for every new endpoint and you will have half the documentation written.

The status code says which category of failure occurred; the body says exactly what happened. Without a body, a 400 forces the developer to guess.

There is a standard error body format, originally defined in RFC 7807 and updated by RFC 9457:

Fields defined by the standard:

Advantages: it is standard, there are libraries that generate and consume it, and type as a URI guarantees global uniqueness. Practical drawbacks: the names are cryptic for anyone who does not know the RFC, type as a URL invites you to invent URLs that nobody maintains, extensions at the same level as the standard fields can collide, and the different Content-Type forces clients to handle two kinds of response.

Aroma Store's decision: an in-house format, for three reasons: (1) the error envelope makes it impossible to mistake a successful response for a failed one, even ignoring the status code; (2) details as an array naturally solves form validation, which is the most frequent case; (3) keeping application/json throughout the API simplifies clients. The decision is documented explicitly alongside the standard alternative, and in 02-08 it will be captured as a reusable schema in OpenAPI.

1. code is contract. In snake_case, stable, unique, and never translated. It is what software compares.
2. message is for humans. Its wording can change and it can be translated (Accept-Language, 02-05). Never compare it in code.
3. details is an array, always present even when empty, so that clients do not have to check whether it exists.
4. No sensitive data: no queries, no stack traces, and no telling whether an email address exists in the database.
5. 5xx responses carry traceId; 4xx responses do not need it.

Implementing all of this as Express middleware is lesson 03-07; here we have only fixed the contract.

The catalogue is as much a part of the contract as the URIs. This is Aroma Store's initial one:

Naming convention: <entity>_<problem> for the specific ones (coffee_not_found) and just <problem> for the cross-cutting ones (invalid_data). The catalogue only grows: withdrawing a code is a breaking change (02-07).

It is the most widespread and most damaging antipattern. Consequences: HTTP clients do not detect the error, automatic retries do not fire, monitoring reports 100% success, proxies cache the error as though it were a good response, and every consumer has to invent its own detection logic. It gives up Richardson level 2 entirely.

If a POST /v1/coffees with priceEuros: "free" causes a 500, the client's system will retry a doomed request and your team will get an alert for somebody else's mistake. Rule: if the request cannot work as it stands, it is a 4xx.

299 Almost OK, 450 Business Error, 600 Failure. Intermediaries interpret unknown codes by their first digit in the best case, and reject them in the worst. Use only registered codes; for the business detail you already have the body's code field.

• 404 for every client error, hiding 400, 403 and 409 behind the same number.
• 401 when permissions are missing: it sends the user off to authenticate again, which is no use and often causes token-refresh loops.
• Useless messages: "Error", "Something went wrong", "Check the log".
• Leaking the stack trace in production.
• A body in a 204: some clients do not read the stream and will leave it half-consumed.

• Confusing 401 and 403. I do not know who you are versus I know who you are and you cannot. Memorise it that way.
• Forgetting Location on a 201. The client is left without the URI of the created resource.
• Forgetting Allow on a 405 or WWW-Authenticate on a 401: they are mandatory by standard and some clients depend on them.
• Using 409 for validation errors. 409 is about the resource's state; bad data is 400.
• Returning 200 with an empty list… for an element. An empty collection is 200; a non-existent element is 404.
• Changing the code of an already published endpoint. Going from 200 to 204 breaks clients that read the body: it is a breaking change (02-07).
• Tip: write out each endpoint's table of codes before implementing it. It is a mandatory column of the reference documentation (02-08).
• Tip: check your errors with curl -i. Seeing the raw response uncovers wrong Content-Types and empty bodies that a polished client hides from you.

State the status code, the error code and the relevant headers for each situation:

1. POST /v1/coffees with no Authorization header.
2. POST /v1/reviews/rev_101/approval with an ordinary customer's token.
3. POST /v1/orders with 100 units of cof_002, which has stock 80.
4. GET /v1/coffees/cof_999.
5. PUT /v1/orders/ord_5001 (Aroma Store only supports PATCH there).
6. POST /v1/orders/ord_5001/payment on an order that has already been paid.
7. PATCH /v1/coffees/cof_001 with Content-Type: application/xml.
8. POST /v1/coffees with {"name": "", "priceEuros": -3}.
9. DELETE /v1/carts/crt_77/items/cof_002, successful.
10. The internal stock service does not respond within 5 seconds.

A legacy API responds like this. Rewrite each response with the correct code, headers and body according to Aroma Store's contract.

Translate this Aroma Store error into the application/problem+json format of RFC 9457, and explain what is gained and what is lost in the translation:

Solution 1

Solution 2

There were two faults here: the code (a validation error belongs to the client, 400, not 500) and the leaking of the stack trace with the server's internal paths.

The message "you must sign in" gives away that the problem is one of authentication, so the correct code is 401, not 403, and the WWW-Authenticate header is missing.

Solution 3

What is gained: a standard format that tools and libraries recognise without configuration; a type as a globally unique URI that can also be a link to the error's documentation; and instance, which identifies the specific occurrence and helps to correlate with the logs.

What is lost: the error envelope, which let you tell a successful response from a failed one at a glance without looking at the code; the uniformity of the Content-Type across the whole API; and the clarity of the names —code/message/details are more direct for the consumer than type/title/detail—. On top of that, the list of validation errors (errors) is an in-house extension in both cases: the RFC does not standardise it, so that part has to be documented either way.

Status codes are the first line of the contract: they say whether the operation went well, whose problem it is and whether retrying makes sense. You now know when to return 201 with Location and when 204 with no body, how to tell 401 from 403 and 404 from 410, to reserve 409 for state conflicts such as insufficient_stock, not to confuse 406 with 415, and to accompany 5xx responses with Retry-After and a traceId without leaking anything internal. You also have a reusable decision tree, Aroma Store's catalogue of business error codes and a reasoned position on application/problem+json. And you know what not to do: 200 with success: false, 500 for data the client mistyped, and invented codes.

So far we have designed the envelope: where the request goes, with which verb and with what outcome. The contents are still missing. In the next lesson, 02-05 Representations, headers and content negotiation, we will design the body of Aroma Store's responses: field names and types, dates, monetary amounts, nulls versus absent fields, the data/total envelope, when to embed and when to link with _links, expansion and sparse fieldsets, and all of content negotiation with Accept, Content-Type, Accept-Language and Accept-Encoding, including the PDF invoice and coffee image uploads.