HTTP Status Codes Explained: A Practical Cheat Sheet
Every HTTP response begins with a three-digit status code, and clients, proxies, caches and search engines all make decisions from that number alone. Most developers know 200 and 404; the trouble lives in the details, such as which redirect keeps the POST body, whether a 401 or a 403 is right, and which failures a client may safely retry. This guide covers the codes you will actually meet and the choices behind them.
The five classes
The first digit tells you the category, and software that does not recognise a specific code is expected to treat it like the first code of its class (an unknown 4xx behaves like 400).
- 1xx informational: the request was received and the process continues. You mainly see
100 Continueand101 Switching Protocols(the WebSocket upgrade). - 2xx success: it worked.
- 3xx redirection: look somewhere else, or use your cached copy.
- 4xx client error: the request itself is at fault; repeating it unchanged will not help.
- 5xx server error: the request may be fine, but the server (or something behind it) failed.
That last distinction drives everything about retries and blame. The full list lives in the HTTP Status Codes reference; the table below keeps to the codes that matter in day-to-day work.
The codes that matter
| Code | Name | Use it when |
|---|---|---|
| 200 | OK | The request succeeded and a body is returned. |
| 201 | Created | A resource was created; send a Location header pointing to it. |
| 204 | No Content | Success with nothing to return, typical for DELETE or PUT. |
| 301 | Moved Permanently | The URL has changed for good; clients may rewrite POST to GET. |
| 302 | Found | Temporary redirect; method rewriting to GET is common. |
| 303 | See Other | Redirect to a GET, such as after a form POST. |
| 304 | Not Modified | Answer to a conditional request; the cached copy is still good. |
| 307 | Temporary Redirect | Temporary, and the method and body must be kept. |
| 308 | Permanent Redirect | Permanent, and the method and body must be kept. |
| 400 | Bad Request | Malformed syntax, bad JSON, invalid encoding. |
| 401 | Unauthorized | No valid credentials supplied (really "unauthenticated"). |
| 403 | Forbidden | Identity is known, but access is refused. |
| 404 | Not Found | No such resource, or you choose not to reveal it. |
| 405 | Method Not Allowed | Right URL, wrong verb; include an Allow header. |
| 409 | Conflict | Duplicate, or the write conflicts with current state or version. |
| 410 | Gone | Deliberately and permanently removed. |
| 415 | Unsupported Media Type | The request Content-Type is not accepted. |
| 422 | Unprocessable Content | Well-formed, but fails validation rules. |
| 429 | Too Many Requests | Rate limit hit; add Retry-After. |
| 500 | Internal Server Error | Unexpected failure, a bug on the server. |
| 502 | Bad Gateway | A proxy got an invalid reply from upstream. |
| 503 | Service Unavailable | Overloaded or in maintenance; temporary. |
| 504 | Gateway Timeout | A proxy gave up waiting for upstream. |
Commonly confused pairs
401 versus 403. The name "Unauthorized" is historical; 401 means the server does not know who you are. A missing, expired or invalid token earns a 401, and it should carry a WWW-Authenticate header. A 403 means the server knows exactly who you are and refuses anyway: a valid user lacking the role. Fixing a 401 means authenticating; retrying with the same credentials against a 403 is pointless. If you work with token-based auth, how JWTs work explains where expiry and signature failures come from, and the JWT Decoder lets you inspect a token's claims.
301 versus 308 (and 302 versus 307). Historically browsers turned a redirected POST into a GET for both 301 and 302. 307 and 308 were introduced to say plainly: repeat the same method with the same body. Use 308 for a permanent API endpoint move where clients POST, and 301 for ordinary page moves, where GET is all anyone does. For redirect after form submission, 303 is the intentional "now fetch this with GET".
400 versus 422. Use 400 when the server cannot even parse the request: broken JSON, an invalid query string, a bad Content-Length. Use 422 when it parses fine but violates the business rules: an email without an at-sign, an end date before the start date. Many APIs just use 400 for both, which is acceptable provided you return a consistent error body that names the failing field.
502 versus 504. Both come from a gateway or load balancer. 502 says the upstream answered with garbage or closed the connection; 504 says it never answered in time. In practice, 502 often means the app crashed or restarted, while 504 means it is alive but too slow.
Retry semantics
A client's retry policy should come from the code class and from whether the method is idempotent. GET, PUT and DELETE are idempotent by definition, so repeating them is safe; POST is not, unless you add an idempotency key.
- 4xx: do not retry unchanged. The exceptions are 408 (request timeout), 425 and 429.
- 429 and 503: retry later, honouring
Retry-Afterif present. - 502, 503, 504: usually transient; retry with exponential backoff and jitter, and a cap on attempts.
- 500: may retry idempotent requests a few times, but a persistent 500 is a bug, not a blip.
Retry-After is either a number of seconds (Retry-After: 30) or an HTTP date. Servers should send it with 429 and 503, and clients should prefer it over their own guess. Backoff with jitter matters because synchronised retries from thousands of clients can turn a brief outage into a longer one.
Caching with 304 and ETag
A 304 only appears in answer to a conditional request. The first response carries a validator, usually ETag: "abc123" or a Last-Modified date. The client stores the body and on the next request sends If-None-Match: "abc123". If nothing has changed, the server replies 304 Not Modified with no body, and the client reuses its stored copy. You save the bandwidth but still pay the round trip.
GET /api/report HTTP/1.1
If-None-Match: "abc123"
HTTP/1.1 304 Not Modified
ETag: "abc123"
The same ETag mechanism, sent as If-Match on a PUT, gives optimistic concurrency: a mismatch returns 412 Precondition Failed (or 409 in simpler designs), so two editors do not silently overwrite each other.
API design tips
- Return 201 with a
Locationheader after creating something, and 204 after a delete that has no body. - Never return 200 with
{"error": ...}in the body; clients, monitors and caches read the status line first. - Use 404 for a missing resource and 403 only when revealing that it exists is harmless. Some APIs deliberately return 404 for resources a caller may not see.
- Give 4xx and 5xx responses a stable JSON shape with a machine-readable code and human message. A tidy payload is easier to read in the JSON Formatter.
- Keep 500 for the unexpected. Map known conditions (conflicts, validation, rate limits) to a specific 4xx so callers can react.
To see this in practice, send a request with the REST API Tester or build the equivalent command with the cURL Builder, then compare the status line and headers. If a request fails with a 400 for no obvious reason, an unencoded character is a common culprit; see URL encoding rules.
A note on 418
Status 418 "I'm a teapot" comes from an April Fools' RFC (2324, the Hyper Text Coffee Pot Control Protocol). It was never meant for real use, but it is reserved in the registry because enough software already used it, and some servers return it as an easter egg or to deflect bots. Do not build behaviour on it, though knowing the joke will save you a minute of confusion the first time one appears in a log.