APIs
Status codes: multiple-choice review
Crux Multiple-choice synthesis across the status-code unit: picking the right code per scenario, the 4xx/5xx ownership split, Retry-After, and the idempotency trap.
Your altitude — climbing toward senior
ZeroJuniorMiddleSenior
You are at senior altitude — in orbitSix scenarios, each one a status code you choose under real conditions. Not “what does 404 mean” — but which code makes the caches, dashboards, and retry loops downstream do the right thing.
Goal
Confirm you can pick the correct status for a given situation and defend it — connecting the 2xx nuances, the 4xx vocabulary, the 4xx/5xx ownership split, and the retry/idempotency rules the unit built toward.
Quiz
Completed
A POST /orders endpoint validates the order, writes it to the DB synchronously, and the resource now exists. What status, and what else must the response carry?
Heads-up 200 will not break anything outright, but it under-specifies: it does not assert that a new resource exists, and tooling that follows Location for the canonical URL gets nothing. 201 + Location is the precise contract for a synchronous create.
Heads-up 202 means 'accepted but not done yet' — for async/queued work. Here the write is synchronous and complete, so 202 would lie to the client that the order is still pending.
Heads-up 204 means success with a deliberately empty body. A create usually wants to return the resource (or at least its Location), so 204 throws away exactly the information the client needs.
Quiz
Completed
An endpoint accepts a request, enqueues it to Kafka, and returns immediately; a worker processes it seconds later. What status is honest?
Heads-up 200 says 'done, here is the result' — synchronous and complete. The work is still in a queue, so the client's UI will show a finished operation that exists nowhere yet. This is the async-vs-sync lie.
Heads-up 201 asserts a resource now exists. The worker has not run, so nothing was created yet. 202 ('accepted, not done') is the honest code.
Heads-up Nothing failed and nothing is unavailable — the request was accepted successfully. 503 would tell clients to back off and retry a request that actually succeeded.
Quiz
Completed
A request arrives with valid JSON, all required fields present and well-typed, but quantity is -3 — a business-rule violation. Which class and code fit best?
Heads-up 400 signals malformed syntax — unparseable JSON, a missing required field. This body parsed cleanly; the values are semantically wrong. 400 tells the client to fix the structure when it should fix the data. Many APIs collapse both into 400, but the 400-vs-422 distinction is what tells the client which to fix.
Heads-up 409 is for a clash with current resource state — a duplicate, a version race. A standalone bad value is not a state conflict; it is a failed business rule, which is 422.
Heads-up A bad input value is the client's fault, not the server's. 500 would wrongly tell every retry loop the request was valid and worth retrying, and would pollute your error-rate dashboards with a non-bug.
Quiz
Completed
A reverse proxy forwards a request to an upstream service, which is up but returns a garbled, truncated response the proxy cannot parse. What status does the proxy return to the client?
Heads-up 500 means the application handling the request threw and did not recover — its own bug. Here the proxy is healthy; the fault is the upstream's malformed response. 502 attributes the blame correctly, which matters for triage.
Heads-up 504 is specifically a timeout — the gateway waited for the upstream and gave up. The upstream did respond here, just with garbage. 502 (bad response) is the right sub-code; 504 (no response in time) is a different failure.
Heads-up 503 means the server is intentionally not serving — overloaded, draining, in maintenance — and should carry Retry-After. A bad upstream response is not intentional unavailability; it is 502.
Quiz
Completed
A client is rate-limited and the server returns 429 with `Retry-After: 30`. The client also runs generic exponential backoff with jitter. What should it do?
Heads-up Retry-After is the server telling you exactly when its window reopens. Ignoring it and retrying earlier just earns another 429 or a ban; retrying much later wastes capacity. Backoff with jitter is the fallback for when the server gives no guidance — not an override.
Heads-up 429 is the explicit retryable exception in the 4xx range — the fix is to slow down, not to resend instantly. Immediate retry on 429 is exactly what trips rate limiters harder.
Heads-up 429 is transient and retryable by design. Honouring Retry-After and retrying is the correct behaviour; failing the user discards a request that would succeed moments later.
Quiz
Completed
A non-idempotent POST /charge times out as 504 with no idempotency key sent. The charge may or may not have run. What is the correct client behaviour?
Heads-up The '5xx is retryable' rule assumes idempotency. POST is not idempotent, and a 504 means the backend may have completed the charge before the gateway gave up. A blind retry without an idempotency key is exactly how this becomes a double charge.
Heads-up 504 means the gateway stopped waiting, not that the work failed. The charge may have succeeded; declaring failure can produce a duplicate manual payment on top of a real charge. The state is unknown, not failed.
Heads-up Without an idempotency key even a single retry can double-charge if the first attempt actually succeeded. The retry count is not the issue; the missing idempotency key is. Add the key and retries become safe.
Recap
The through-line: the first digit is a machine instruction, and the precise sub-code carries real contract information. 2xx splits into 201 (+Location) for a synchronous create, 202 for accepted-but-async, 204 for deliberately empty success. The 4xx vocabulary tells the client what to fix — 400 (syntax) vs 422 (values) vs 409 (state). The 5xx sub-codes attribute blame — 500 your bug, 502 a bad upstream, 503 intentional unavailability, 504 a timeout where the work may secretly have completed. Retry 5xx and 429, honour Retry-After before backing off, and never blindly retry a non-idempotent request after a timeout — reach for an idempotency key instead.