HTTP Status Codes Explained

Summary: six defects in status codes or headers (R1, R2, R4, R6, R7, R8), three correct responses (R3, R5, R9), and two gateway codes that are correct but point at a problem behind the gateway (R10 to investigate, R11 a defect). The details follow row by row; each expected result comes from the conventions.

R1 — defect (C1). Expected result: 201 Created with Location: /api/v2/orders/58213. A 200 only says "it worked"; it does not say that a new resource exists, and a client that checks for 201, or reads the Location header to open the new order, cannot rely on this response.

R2 — defect (C2). The body parses and 0 breaks the rule of 1 or more, so the expected result is 422 with a JSON error that names the field quantity. The 500 is the failure; the defect behind it is missing validation: the value reached code that could not handle it, and a 500 is never the correct answer to bad input. Because 0 and 1 are the two boundary values of this rule, check that 1 is accepted, and also try -1, 1.5, "two" and a missing quantity to see how far the missing validation goes.

R3 — correct (C2). A body that cannot be parsed gets 400 with the JSON error body. A 422 would be wrong here, because nothing could be read to validate.

R4 — defect (C3). No token means "not authenticated": expected result 401 Unauthorized with WWW-Authenticate: Bearer, and RFC 9110 requires that header on every 401. A 403 tells the app "you are signed in but not allowed", so instead of sending the customer to the sign-in screen it shows a permission error. Retest with an expired token too, because C3 covers both cases, and keep one check that 403 still appears where it belongs: a valid token used for an action it is not allowed to perform.

R5 — correct (C4). The order exists but belongs to customer B. The team chose 404 so that the API does not reveal which order numbers exist, a use of 404 the guide describes (the server prefers not to say whether the resource exists). A 403 here would be a defect against C4, because it would confirm that order 58101 exists. The check that matters is the comparison: status, headers and body must be identical to those for the unknown order 99999999, and they are.

R6 — defect (C5 and C8). Expected result: 409 Conflict with the JSON error body, because cancelling clashes with the order’s current state (already shipped). A 200 with "status":"error" hides the failure: the app may tell the customer that the order was cancelled, and monitoring counts the call as a success. Also check the side effects: the order must still be in the shipped state, and no refund may have started.

R7 — defect (C6). 429 is the right code for the 61st request, but the Retry-After header that C6 requires is missing, so the app cannot know when to try again: it either sends more requests that get 429 or waits longer than it needs to. Check the boundary as well: the 60th request in the same minute must succeed.

R8 — defect (C7). Expected result: 308 Permanent Redirect with Location: /api/v2/orders. On a 301 a client may change POST to GET (RFC 9110 allows this for historical reasons), and that is exactly what happened: the basket never reached /v2, no order was created, and the last response in the chain is a 200, so the app may report success. The guide’s advice is to prefer 308 over 301 for APIs. Ask which app versions still call /v1: the answer decides how urgent this is.

R9 — correct. 304 is not an error: the order has not changed since the app cached it with ETag "a7f3", so the server sends no body and the app shows its cached copy. Test the opposite case as well: after the order changes (for example after a cancellation), the same request must return 200 with the new body and a new ETag; otherwise customers see a stale status.

R10 — not a defect in the status code; a question to investigate. 502 means the load balancer received an invalid response, or no response, from the application, which fits an application server restarting during the 14:02 deployment. Record the time, the build and the request, and retest after the deployment. If 502 appears outside deployments, it points to the application crashing or dropping connections: report it with the application logs. Two questions for the team: should the load balancer stop sending requests to a server before it restarts during a deployment, so that clients never see 502? And can the app handle an HTML error page where C2 promises a JSON body?

R11 — the 504 itself is correct: the load balancer waited 30 seconds and the application did not answer in time. The defect is behind it: a search over a long history (2019 to 2026) does not finish within the 30 seconds the gateway allows. Narrow the date range to find roughly where it starts to fail, record the response times, and report it as a performance defect. Ask the product owner whether there is a maximum date range: if there is, a range the API will not serve should be rejected with 422 (C2) instead of timing out. Repeating the same request will not help.

The developer’s question: not as it stands. Retry automatically only when both are true: the code is temporary (502, 503, 504) and the method is idempotent (GET, PUT, DELETE). R2 must not be retried, for two reasons. Its 500 is caused by the request itself, so it comes back the same every time. And POST is not idempotent, which is the bigger risk: if POST /v2/orders gets a 502 or 504, the server may already have created the order before the response was lost, and an automatic retry can create a second one. After a failed POST the app should check the order list with a GET before it offers to send again, and the developers should explain how the API prevents duplicate orders. R10 is safe to retry (GET, temporary code, with backoff). R11 is a GET too, but repeating a request that is too heavy only adds load and times out again, so keep the number of retries small and use backoff. Finally, 429 is a 4xx that may be retried, but only after the Retry-After time, which is one more reason R7 matters.

Report R8 first. Title, for example: "POST /v1/orders answers 301 instead of 308; the client resends it as GET and no order is created". It comes first because customers on any app that still calls /v1 lose their orders without any error message, and the chain ends with a 200. Then R6 (a failed cancellation shown as a success) and R4 (a missing token reported as a permission problem, so the app never sends the customer to sign in). If you put R6 first because you know that every app has moved to /v2, that is a sound reason; what matters is that the priority comes from the impact on customers. After the fixes, run the same rows again as confirmation tests.

To check your work: every row should have the expected code and, where the conventions ask for one, the header (Location, WWW-Authenticate, Retry-After). If you marked R3, R5 or R9 as a defect, reread what the guide says about 400 vs 422, about 404 (the server may prefer not to say whether a resource exists) and about 304 (not an error).