Web
Understanding HTTP status codes
Status codes are the server telling you what happened in one number. Learn the shape of each class and you can debug most APIs without reading a manual.
The five classes
| Range | Meaning |
|---|---|
| 1xx | Informational, rarely seen directly |
| 2xx | Success |
| 3xx | Redirection |
| 4xx | Client error (your request was wrong) |
| 5xx | Server error (their side broke) |
The mental model: 4xx means fix your request, 5xx means it is not your fault.
The ones worth memorizing
Success
- 200 OK, the default happy path
- 201 Created, use after a successful POST that made a resource
- 204 No Content, success but nothing to return (common for DELETE)
Redirects
- 301 Moved Permanently, update your bookmarks and links
- 302 Found, temporary redirect
- 304 Not Modified, your cached copy is still good
Client errors
- 400 Bad Request, malformed input
- 401 Unauthorized, you are not authenticated (misnamed, really means unauthenticated)
- 403 Forbidden, authenticated but not allowed
- 404 Not Found
- 409 Conflict, e.g. a duplicate or a version clash
- 422 Unprocessable Entity, syntactically fine but semantically invalid
- 429 Too Many Requests, you got rate limited
Server errors
- 500 Internal Server Error, the catch-all crash
- 502 Bad Gateway, an upstream service returned garbage
- 503 Service Unavailable, overloaded or down for maintenance
- 504 Gateway Timeout, an upstream service took too long
401 vs 403
These trip people up. 401 means the server does not know who you are, so send credentials. 403 means it knows exactly who you are and the answer is still no.
Seeing them yourself
GET /api/users/42 HTTP/1.1
Host: example.com
HTTP/1.1 200 OK
Content-Type: application/json
curl -i https://example.com/api/health # -i prints the status line and headers