APIs from zero

Status codes

The first thing in every answer is a three-digit status code. What the five families mean, the codes you'll meet every day, and what to do about each.

Every response starts with a status code: three digits that say, before anything else, how it went. The first digit tells you the family:

Starts withFamilyMeans
1xxInformational"Wait, there's more" — rare; you'll hardly see these
2xxSuccessIt worked
3xxRedirectionIt's somewhere else — go there
4xxClient errorYour request was wrong — fix it before trying again
5xxServer errorThe server failed — not your fault, maybe try again later

That split — 4xx is you, 5xx is them — is the most useful thing in this lesson.

The codes you'll meet every day

2xx — it worked

CodeNameWhen
200OKThe usual success, with data in the body
201CreatedA POST made something new; often a Location header says where it is
202Accepted"Got it — I'll do it later" (a job was queued)
204No ContentIt worked, and there's nothing to send back (common for DELETE)

3xx — look elsewhere

CodeNameWhen
301 / 308Moved permanentlyThe address changed for good; the Location header has the new one
302 / 307Found / Temporary redirectGo there for now — common after a sign-in
304Not Modified"You already have the latest" — when the client asked only if changed

Most tools follow redirects automatically, a few hops deep.

4xx — the request was wrong

CodeNameUsually meansWhat to do
400Bad RequestThe body or parameters don't make sense (bad JSON, a missing field)Read the answer's body — it usually says which field
401UnauthorizedNot signed in: no token, a wrong one, or an expired oneCheck the auth; get a fresh token
403ForbiddenSigned in, but not allowed to do this — or a firewall said noCheck permissions; if every request is 403, a firewall may be blocking you
404Not FoundNo such thing at this address (or the path is wrong)Check the path and the id
405Method Not AllowedRight address, wrong method (POST where only GET works)Check the method
409ConflictClashes with the current state (it already exists; someone changed it first)Fetch the latest and try again
415Unsupported Media TypeThe body's Content-Type isn't one it readsSet the right Content-Type
422UnprocessableThe JSON is fine, but the values aren't (a negative quantity)Fix the values the answer names
429Too Many RequestsYou're being rate limitedSlow down; a Retry-After header says how long to wait

401 and 403 confuse everyone: 401 = "who are you?", 403 = "I know who you are, and no."

5xx — the server failed

CodeNameUsually means
500Internal Server ErrorA bug or crash on the server — the request triggered something it didn't handle
502Bad GatewayA server in front (a proxy, a load balancer) got a bad answer from the one behind it
503Service UnavailableOverloaded or down for maintenance — try later
504Gateway TimeoutThe server behind the proxy didn't answer in time

5xx codes are the server team's problem — but finding them is the tester's job. And under load they're the clearest sign that something gave way: a test where 500s and 503s start appearing at 200 users tells you where the limit is.

A status code isn't the whole story

Two traps:

  • 200 with an error inside. Some APIs answer 200 OK with { "success": false, "error": "Card declined" }. The status says fine; the body says failed. A test that only checks the status passes something broken. That's why checks look at the body too.
  • The wrong success code. An API that answers 200 where it should answer 201 might be fine — or might be telling you it didn't create anything. Know which code the API is meant to give.

Key takeaways

  • 2xx worked, 3xx go elsewhere, 4xx your request was wrong, 5xx the server failed.
  • 401 = not signed in; 403 = not allowed; 429 = too many requests, slow down.
  • A 200 can still be a failure — check the body, not just the code.

In the app: Reading the answer · Failing status codes in a report · Blocked: 429 or 403

Next: JSON

A question these lessons don’t answer? Write to support@apitestcenter.com — we add lessons for the questions people ask.