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 with | Family | Means |
|---|---|---|
| 1xx | Informational | "Wait, there's more" — rare; you'll hardly see these |
| 2xx | Success | It worked |
| 3xx | Redirection | It's somewhere else — go there |
| 4xx | Client error | Your request was wrong — fix it before trying again |
| 5xx | Server error | The 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
| Code | Name | When |
|---|---|---|
| 200 | OK | The usual success, with data in the body |
| 201 | Created | A POST made something new; often a Location header says where it is |
| 202 | Accepted | "Got it — I'll do it later" (a job was queued) |
| 204 | No Content | It worked, and there's nothing to send back (common for DELETE) |
3xx — look elsewhere
| Code | Name | When |
|---|---|---|
| 301 / 308 | Moved permanently | The address changed for good; the Location header has the new one |
| 302 / 307 | Found / Temporary redirect | Go there for now — common after a sign-in |
| 304 | Not 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
| Code | Name | Usually means | What to do |
|---|---|---|---|
| 400 | Bad Request | The body or parameters don't make sense (bad JSON, a missing field) | Read the answer's body — it usually says which field |
| 401 | Unauthorized | Not signed in: no token, a wrong one, or an expired one | Check the auth; get a fresh token |
| 403 | Forbidden | Signed in, but not allowed to do this — or a firewall said no | Check permissions; if every request is 403, a firewall may be blocking you |
| 404 | Not Found | No such thing at this address (or the path is wrong) | Check the path and the id |
| 405 | Method Not Allowed | Right address, wrong method (POST where only GET works) | Check the method |
| 409 | Conflict | Clashes with the current state (it already exists; someone changed it first) | Fetch the latest and try again |
| 415 | Unsupported Media Type | The body's Content-Type isn't one it reads | Set the right Content-Type |
| 422 | Unprocessable | The JSON is fine, but the values aren't (a negative quantity) | Fix the values the answer names |
| 429 | Too Many Requests | You're being rate limited | Slow 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
| Code | Name | Usually means |
|---|---|---|
| 500 | Internal Server Error | A bug or crash on the server — the request triggered something it didn't handle |
| 502 | Bad Gateway | A server in front (a proxy, a load balancer) got a bad answer from the one behind it |
| 503 | Service Unavailable | Overloaded or down for maintenance — try later |
| 504 | Gateway Timeout | The 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:
200with an error inside. Some APIs answer200 OKwith{ "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
200where it should answer201might 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