Glossary · API testing
HTTP status code
Also called: HTTP status codes, status code, status codes, response code
Definition
The three-digit number in every HTTP response that says whether the request succeeded, was redirected, or failed because of the client or the server.
An HTTP status code is the server’s short answer to a request. The first digit gives the class: 1xx informational, 2xx success, 3xx redirection, 4xx client error (the request was wrong) and 5xx server error (the request may have been fine, but the server failed). Asserting the exact status code is usually the first check in any API test.
The codes testers use most
| Code | Meaning | Typical use |
|---|---|---|
200 OK |
Success with a body | GET, or an update that returns the resource |
201 Created |
A resource was created | POST, with a Location header |
204 No Content |
Success, no body | DELETE, some PUTs |
301 / 302 / 304 |
Moved, found elsewhere, not modified | Redirects and caching |
400 Bad Request |
Malformed or invalid request | Broken JSON, wrong types |
401 Unauthorized |
Not authenticated | Missing, expired or invalid token |
403 Forbidden |
Authenticated but not allowed | Valid user, wrong role |
404 Not Found |
No such resource | Unknown id, or hiding a forbidden one |
409 Conflict |
Clashes with current state | Duplicate email, version conflict |
422 Unprocessable Content |
Well-formed but fails validation | Business rule violations |
429 Too Many Requests |
Rate limit exceeded | Often with Retry-After |
500 / 502 / 503 / 504 |
Server error, bad gateway, unavailable, gateway timeout | Bugs and infrastructure |
401 versus 403
Despite its name, 401 Unauthorized is about authentication: the server does not know who you are. The fix is to log in or send a valid token, and the response should include a WWW-Authenticate header. 403 Forbidden is about authorization: the server knows who you are and you are not allowed to do this. Logging in again will not help. A test suite should cover both: no token, an expired token, and a valid token for a user without the right permission.
Common mistakes
- Only checking for 200. Most defects live in error paths. Invalid input should get a
4xx; a500means unhandled input and is worth a bug report. - Errors with 200 status. An error message in a
200body breaks clients and monitoring. - Inconsistent conventions. Some APIs use
400for all bad input, others reserve422for validation failures. Either is fine; mixing them within one API is the bug.