⚡ SmartDevTools

HTTP Status Codes Explained: A Practical Cheat Sheet

By SmarTech Apps · Published 2026-11-18 · 7 min read

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).

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

CodeNameUse it when
200OKThe request succeeded and a body is returned.
201CreatedA resource was created; send a Location header pointing to it.
204No ContentSuccess with nothing to return, typical for DELETE or PUT.
301Moved PermanentlyThe URL has changed for good; clients may rewrite POST to GET.
302FoundTemporary redirect; method rewriting to GET is common.
303See OtherRedirect to a GET, such as after a form POST.
304Not ModifiedAnswer to a conditional request; the cached copy is still good.
307Temporary RedirectTemporary, and the method and body must be kept.
308Permanent RedirectPermanent, and the method and body must be kept.
400Bad RequestMalformed syntax, bad JSON, invalid encoding.
401UnauthorizedNo valid credentials supplied (really "unauthenticated").
403ForbiddenIdentity is known, but access is refused.
404Not FoundNo such resource, or you choose not to reveal it.
405Method Not AllowedRight URL, wrong verb; include an Allow header.
409ConflictDuplicate, or the write conflicts with current state or version.
410GoneDeliberately and permanently removed.
415Unsupported Media TypeThe request Content-Type is not accepted.
422Unprocessable ContentWell-formed, but fails validation rules.
429Too Many RequestsRate limit hit; add Retry-After.
500Internal Server ErrorUnexpected failure, a bug on the server.
502Bad GatewayA proxy got an invalid reply from upstream.
503Service UnavailableOverloaded or in maintenance; temporary.
504Gateway TimeoutA 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.

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

  1. Return 201 with a Location header after creating something, and 204 after a delete that has no body.
  2. Never return 200 with {"error": ...} in the body; clients, monitors and caches read the status line first.
  3. 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.
  4. 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.
  5. 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.

Try the tools

Keep reading