API status codes testers should actually care about

Status codes are the first thing an API tells you and the first thing teams get wrong. You don't need to memorise the full registry — most of it never shows up in real testing. You need a working grasp of the dozen that matter, what each one promises, and the instinct to notice when the status line and the response body disagree. This is the deep dive behind the first item in the 12 API bugs I check first.

The mental model: the code is a promise

A status code is the server promising what kind of response this is, before you read the body. 2xx says "it worked." 4xx says "you got it wrong." 5xx says "I got it wrong." The whole skill is checking that the promise matches reality — that a "success" actually succeeded and a "client error" was actually your fault.

The success codes that aren't interchangeable

• 200 OK — generic success. Fine for reads.
• 201 Created — a resource was created. A POST that makes something should return 201 (often with a Location header pointing at it), not 200. Returning 200 from a create blurs "made it" and "found it."
• 202 Accepted — "I've taken the request but haven't finished." For async work. Testing a 202 as if the work is done is a classic mistake — the job might still fail later.
• 204 No Content — success, deliberately empty body (common for DELETE or an update with nothing to return). A 204 with a body is a contradiction; a test expecting JSON from a 204 will break.

The client errors that get confused

• 400 Bad Request — malformed/invalid input. The catch-all for validation failures.
• 401 Unauthorized — actually means unauthenticated: "I don't know who you are." Missing or bad credentials.
• 403 Forbidden — "I know who you are, and you're not allowed." The authorization code.
• The 401 vs 403 test: no token should give 401; a valid token for the wrong resource should give 403. Swapping these is a real bug — and a 403 where it should be 401 (or vice versa) can leak whether a resource exists.
• 404 Not Found — missing resource. Sometimes used deliberately instead of 403 to avoid confirming a record exists.
• 409 Conflict — the request collides with current state (duplicate create, edit conflict, already-refunded order). Often missing, so duplicates slip through as 200.
• 422 Unprocessable Entity — syntactically valid but semantically wrong (well-formed JSON, but the values violate a rule). Some APIs use 400 for everything; consistency matters more than which they pick.
• 429 Too Many Requests — rate limited. Should come with Retry-After, not a 500.

The server errors

• 500 Internal Server Error — the server broke. For a tester this is gold: a 500 from invalid input means a validation gap (an unhandled exception), which is a bug even though "the input was wrong." Bad input should be a 4xx, never a 5xx.
• 502 / 503 / 504 — upstream/gateway/timeout problems. Worth distinguishing when testing resilience, but 500 is the one you'll log most.

The judgement: when the code lies

The highest-value skill isn't the table above — it's noticing the mismatch between the status line and the body:

• 200 OK wrapping {"error": "..."} — the single most common API bug. Every happy-path test passes; nothing actually worked.
• 200 on a failed create (no resource made).
• 500 on bad input (should be 400).
• 404 where 403 was meant (or the reverse), leaking existence.
• 200 with an empty body where the contract promised data.

Always assert the code and the body together. A test that checks only status === 200 is half a test.

Where this fits

Status codes are the foundation of API testing; get them right and the rest of the 12 API bugs and list-endpoint traps read more clearly. The API testing checklist and the tools directory cover putting these assertions into a suite.

Status-code checks

• POST that creates returns 201 (not 200); DELETE/empty-update returns 204
• Async work returns 202 — don't assert completion on it
• No token → 401; valid token, wrong resource → 403
• Duplicates/conflicts return 409, not a silent 200
• Invalid input returns 4xx (400/422) — never a 500
• Rate limiting returns 429 + Retry-After
• Every assertion checks the status line AND the body together