HTTP status codes
Every HTTP status code you'll actually meet, explained in one line each — grouped by class, filterable, and printable for the desk.
Last updated
2xx — Success
| Code | Meaning |
|---|---|
| 200 OK | It worked; the response body is the answer. |
| 201 Created | It worked and a new resource now exists — Location header says where. |
| 202 Accepted | Received, queued for processing later; no promise it will succeed. |
| 204 No Content | It worked and there is deliberately nothing to send back. |
| 206 Partial Content | Here is the byte range you asked for — resumable downloads live here. |
3xx — Redirection
| Code | Meaning |
|---|---|
| 301 Moved Permanently | Gone for good; update your links — browsers and Google cache this. |
| 302 Found | Temporarily elsewhere; keep using the old URL. |
| 304 Not Modified | Your cached copy is still current; body intentionally empty. |
| 307 Temporary Redirect | Like 302, but the method and body must not change on the retry. |
| 308 Permanent Redirect | Like 301, but the method and body must not change on the retry. |
4xx — Client errors
| Code | Meaning |
|---|---|
| 400 Bad Request | The server can't parse or accept what you sent — malformed syntax or invalid fields. |
| 401 Unauthorized | Misnamed: you are unauthenticated — log in (or fix the token) and retry. |
| 403 Forbidden | Authenticated, but this identity may not do that — logging in again won't help. |
| 404 Not Found | No resource at this URL — or the server won't admit one exists. |
| 405 Method Not Allowed | The URL exists but not for this verb; Allow header lists what works. |
| 408 Request Timeout | You took too long to finish sending; the server hung up. |
| 409 Conflict | Valid request, but it collides with current state — edit conflicts, duplicate names. |
| 410 Gone | Existed once, deliberately removed forever — a 404 with a tombstone. |
| 413 Payload Too Large | The body exceeds the server's size limit — common on file uploads. |
| 415 Unsupported Media Type | The Content-Type you sent isn't one the endpoint accepts. |
| 418 I'm a teapot | An April Fools RFC made real — used by sites to reject automated junk. |
| 422 Unprocessable Entity | Parsed fine, failed validation — the classic "form errors" status for APIs. |
| 429 Too Many Requests | Rate limited; Retry-After says how long to back off. |
5xx — Server errors
| Code | Meaning |
|---|---|
| 500 Internal Server Error | The server's code crashed; nothing you sent was necessarily wrong. |
| 501 Not Implemented | The server doesn't support this method at all, for any resource. |
| 502 Bad Gateway | A proxy got a garbage response from the server behind it. |
| 503 Service Unavailable | Overloaded or down for maintenance — temporary, retry later. |
| 504 Gateway Timeout | A proxy gave up waiting for the server behind it. |
1xx — Informational
| Code | Meaning |
|---|---|
| 100 Continue | Headers look fine; go ahead and send the body. |
| 101 Switching Protocols | Upgrading this connection — how every WebSocket begins. |
Worth remembering
- →The class digit is the contract: 2xx you're done, 3xx go elsewhere, 4xx fix your request, 5xx wait or escalate — an unfamiliar code still tells you which side is broken.
- →401 vs 403 is the pair worth memorizing: 401 means prove who you are, 403 means we know exactly who you are.
Questions
What is the difference between 401 and 403?
401 means the request was not authenticated — the server does not know who you are, and a login may fix it. 403 means it knows and refuses anyway, so retrying with the same credentials will not help.
When should I use 404 rather than 403?
Returning 404 for a resource that exists but is not yours avoids confirming its existence, which matters where an identifier is guessable. It is a deliberate trade of accuracy for not leaking information.
Which redirect should I use?
301 for permanent, which tells clients and search engines to update; 302 for temporary. Use 307 and 308 when the method must be preserved, since older clients turn a POST into a GET on 301 and 302.
What does 422 mean against 400?
400 means the request was malformed and could not be parsed; 422 means it parsed fine and the contents failed validation. The distinction tells a client whether to fix the syntax or the values.
Should an API ever return 200 with an error body?
It is common and it defeats every layer that reads status codes — monitoring, retries, caches and client libraries all treat 200 as success. Use the status code for the outcome and the body for the detail.