Three digits that carry the outcome of an HTTP exchange — nothing more, nothing less. Everything else is convention built on top.

Every HTTP response begins with a status line: a protocol version, a three-digit status code, and a short human-readable reason phrase. The code is the part machines act on; the reason phrase is decorative and can be changed or omitted without breaking anything compliant. When a browser retries a request, when an API client decides whether to back off, when a load balancer marks a server unhealthy, when a CDN decides whether to cache a response — the status code is what drives that decision.

The status code system was introduced with HTTP/1.0 (RFC 1945, 1996) and refined significantly in HTTP/1.1 (RFC 2616, 1999). The modern authoritative source is RFC 9110 — HTTP Semantics (June 2022), which obsoletes the older RFC 7231 and consolidated semantics that apply across HTTP/1.1, HTTP/2, and HTTP/3. The registry of all officially recognized codes is maintained by IANA at the “Hypertext Transfer Protocol (HTTP) Status Code Registry,” and new codes are added by IETF standards-track or well-reviewed specification documents — codes cannot simply be invented by a vendor and expected to mean anything outside that vendor’s ecosystem, though in practice this happens constantly (more on that later).

Every HTTP response, whether from a monolith or a globally distributed edge, opens with the same three ordered pieces of information.

HTTP/1.1 200 OK

Three parts, always in this order:

• Protocol version — HTTP/1.1, HTTP/2, or HTTP/3. In HTTP/2 and HTTP/3 the status is technically sent as a pseudo-header (:status) rather than a literal status line, but the semantics are identical.
• Status code — the three-digit number that carries all the machine-actionable meaning.
• Reason phrase — free text such as “OK,” “Not Found,” or “I’m a teapot.” Purely for human readability; RFC 9110 explicitly says a client MUST ignore the reason phrase and act only on the numeric code, and a server MAY send a different reason phrase than the one shown in the spec, or none at all.

Along with the status line, a response typically carries headers that add precision the code alone can’t express — Location for redirects, Retry-After for rate limits and maintenance windows, WWW-Authenticate for 401s, Allow for 405s. A status code without its expected companion headers is a common source of subtle bugs, and several are called out in the sections below.

Before diving into individual codes, it helps to see all five classes side by side. Every registered status code lives in exactly one of these buckets.

Automated retry logic, alerting, and SLOs all hinge on getting this distinction right. Returning 500 for bad user input pages every on-call engineer for no reason; returning 400 for a database outage hides a real incident behind “user error.” Every one of the anti-patterns catalogued later in this reference is, at root, some failure to honor this boundary.

Provisional responses. The request was received and understood; processing continues. A 1xx is always followed by a final response and is never the end of the transaction.

The request was received, understood, and accepted. What “accepted” means varies by code — fully processed, queued, or partially satisfied.

Further action is needed to complete the request, usually fetching a different URI. This is the class most prone to subtle, hard-to-debug mistakes because the codes differ in behavior that only shows up under specific client conditions.

The request, as sent, cannot or will not be fulfilled due to something about the request itself. Except for HEAD responses, the body should explain what’s wrong in a way a client (or the developer reading logs) can act on.

The server failed to fulfill an apparently valid request. By definition, the client did nothing wrong — these are the codes that should page an on-call engineer, not a frontend developer.

These pairs (and trios) get mixed up constantly in code review. Each mistake has a specific, concrete consequence.

401 vs 403 — authentication vs authorization

The name “401 Unauthorized” is a well-known misnomer baked in from the earliest HTTP specs — it should have been called “Unauthenticated.” This causes real confusion in API design: a request with a valid-but-insufficiently-privileged token should return 403, not 401, but many codebases return 401 for both cases out of habit, which breaks client retry logic (a client that sees 401 will often try to refresh its auth token and retry — pointless and wasteful if the real problem is a permissions gap that a token refresh can never fix).

301 / 302 / 307 / 308 — permanence and method preservation

Two independent axes are being encoded here: permanence (does this affect caching and SEO link equity) and method preservation (does the client keep the original verb and body). 301/302 predate the method-preservation guarantee; 307/308 were added specifically to remove the ambiguity for non-GET redirects. If you’re redirecting a REST API’s POST/PUT/DELETE endpoint, use 307 or 308 — never 301/302.

502 vs 503 vs 504 — where exactly did it fail?

Distinguishing these matters enormously for incident response: 502 usually points at an application crash, 504 usually points at a slow dependency (database, downstream API) or a hung connection pool, and 503 is often intentional (a readiness probe correctly failing during a rolling deploy). Collapsing all three into one alert bucket makes root-causing an outage much slower.

400 vs 422 — malformed vs unprocessable

400 is for requests that are broken as HTTP: invalid JSON, wrong content-type, missing required framing. 422 is for requests that are perfectly valid HTTP and valid JSON, but fail domain rules once the server actually looks at the values — an email field that isn’t a valid email, a date range where the end precedes the start, a username that’s already taken combined into one request the server can fully parse. Many frameworks (Rails, Laravel) draw this line by default; many hand-rolled APIs don’t bother and just return 400 for everything, which is defensible but throws away a useful signal for API consumers building form-validation UI.

Real HTTP traffic is full of deliberate deviations from the spec and accidental misclassifications. Both matter for interoperability — and the difference between the two comes down to whether the deviation is documented.

Always returning 200, errors encoded in the body

Some APIs (older SOAP-over-HTTP services, a handful of REST APIs, many GraphQL implementations) return 200 OK for every request regardless of outcome, with success/failure indicated inside a JSON envelope ({"ok": false, "error": "..."}). GraphQL does this somewhat by design, because a single HTTP request can contain multiple queries with independent success/failure. The trade-off is real: it defeats HTTP-layer tooling — caches, CDNs, load-balancer health checks, generic retry middleware, and API gateways that make decisions based on status code all become blind to actual failures. This is a deliberate, debated design choice, not simply “wrong,” but it should be a conscious decision, not a default.

Using 404 to hide the existence of a resource

A very common, deliberate pattern in access-controlled systems: instead of returning 403 for a resource a user isn’t allowed to see, return 404 — so an attacker probing for valid resource IDs can’t distinguish “doesn’t exist” from “exists but you can’t see it.” GitHub famously does this for private repositories: a request for a private repo you don’t have access to returns 404, not 403, precisely to avoid leaking that the repo exists at all. This is a legitimate, security-motivated exception to the “use the most specific code” guideline, and it’s worth documenting explicitly wherever it’s used, since it looks like a bug to anyone reading the code without that context.

Vendor-specific unofficial codes

Covered in the 4xx/5xx sections above (419, 420, 430, 440, 449, 509, 599). These work within a closed client/server pair that both understand the convention, but any standards-compliant intermediary (proxy, CDN, monitoring tool) that doesn’t recognize the specific code will fall back to generic class-level handling — which is usually fine, but occasionally surprising if the intermediary has class-specific behavior (e.g. automatically retrying all unrecognized 5xx codes).

Returning 500 for client-caused failures

Caching-unsafe misuse of 3xx

A short list of habits that, followed consistently, prevent the vast majority of status-code misuse in production APIs.

Status codes are a small, closed vocabulary doing a lot of work: they’re the primary channel through which caches, proxies, load balancers, monitoring systems, and client libraries make automated decisions, entirely independent of whatever a response body says in prose. Picking the right one — and pairing it with the headers it expects — is one of the cheapest, highest-leverage decisions available when designing an HTTP-based system.