HTTP status codes: the decisions each number carries

Five classes and the history behind them

The first digit of the code reveals the category, and that reading alone tells you which side to look at. It is the triage a good developer does in half a second before opening any log. The meaning of each class is fixed in RFC 9110 (HTTP Semantics), the document that today serves as the reference for HTTP/1.1, HTTP/2 and HTTP/3 at once.

That split looks obvious today, but it took decades to settle. The numbering was born lean and gained codes as the web discovered new problems, from Wi-Fi portals to rate limiting. It is worth knowing the timeline, because it explains why near-identical pairs like 302 and 307 exist: they are from different eras, created to fix ambiguities from the previous generation.

1. May 1996RFC 1945, HTTP/1.0

   The first documented version. Introduces the status line and a handful of codes (200, 301, 302, 400, 404, 500).

2. January 1997RFC 2068, HTTP/1.1

   The first standardized cut of HTTP/1.1, with persistent connections and more codes.

3. June 1999RFC 2616, HTTP/1.1 revised

   The revision that stood as the reference for fifteen years, in a single monolithic document.

4. June 2014RFC 7230–7235

   RFC 2616 is split into six documents (syntax, semantics, conditionals, range, caching, authentication).

5. June 2022RFC 9110 / 9111 / 9112

   The current reference: semantics (9110), caching (9111) and HTTP/1.1 (9112). Obsoletes the 723x series and applies to every version.

Redirecting without breaking the method: 301 vs 308, 302 vs 307

The 2xx block is the calm one: 200 OK is success with a body, 201 Created confirms a POST created a resource (usually with a Location header) and 204 No Content is the silent success, typical of a DELETE. The real trap is in 3xx, where one subtle decision separates a harmless redirect from a bug that only shows up in production: does the code change the HTTP method?

Here is the detail RFC 9110 records in a note: for historical reasons, when following a 301 (§15.4.2) or a 302 (§15.4.3) the client MAY change the method from POST to GET. Browsers have done this for decades, and the spec merely describes the real behavior. The 307 Temporary Redirect (§15.4.8) and 308 Permanent Redirect (§15.4.9) were created precisely to NOT allow that change: they preserve the method and body. The permanent/temporary axis is orthogonal to this, 301 and 308 are permanent; 302 and 307 are temporary.

Worked example #1: a checkout sends a POST with the purchase amount. If the server responds 302, the browser follows the redirect by switching the method to GET and DROPPING the body, the payment is lost on the way and the confirmation endpoint gets an empty GET. With 307, the client repeats the POST with the same body. See the difference byte by byte:

# Envio um formulário de pagamento com POST
POST /checkout HTTP/1.1
Host: loja.com
Content-Type: application/x-www-form-urlencoded

valor=199.90&metodo=cartao

# (A) Servidor responde 302 -> o navegador troca POST por GET
HTTP/1.1 302 Found
Location: /obrigado

GET /obrigado HTTP/1.1          <- metodo virou GET, corpo descartado
Host: loja.com

# (B) Mesmo fluxo com 307 -> o cliente REPETE metodo e corpo
HTTP/1.1 307 Temporary Redirect
Location: /obrigado

POST /obrigado HTTP/1.1         <- continua POST, corpo preservado
Host: loja.com
Content-Type: application/x-www-form-urlencoded

valor=199.90&metodo=cartao

The rule of thumb falls out on its own: to permanently move a plain page (GET) and preserve ranking, 301 is the classic and Google treats 301 and 308 as equivalent when consolidating signals. To permanently move an endpoint that receives POST, use 308. For a passing detour, 302 is enough, unless the method matters, and then it is 307. Check the meaning, RFC and cacheability of any code in the tool below before you choose.

4xx: the request is yours, 401 vs 403, 404 vs 410

The 4xx points at what you sent. Some are blunt: 400 Bad Request is a malformed request, 405 Method Not Allowed is the wrong verb (and the server should list the accepted ones in the Allow header), 409 Conflict is a state clash. But two pairs make people waste hours hunting a bug in the wrong place: 401 versus 403 and 404 versus 410. The difference is not one of severity, it is one of meaning.

The other pair lives on the border between backend and SEO. 404 Not Found (§15.5.5) says “does not exist at this URL”, it could be a wrong route, a removed resource, or even the server hiding that the resource exists. 410 Gone (§15.5.11) is more assertive: “it existed and was removed on purpose”. The question that matters is not technical, it is what each one signals to Googlebot.

304 Not Modified: the exchange that saves bandwidth

The 304 Not Modified (§15.4.5) is the one 3xx that redirects nothing, it is the engine of cache revalidation. The idea: instead of re-downloading a resource that may not have changed, the client asks “did it change?” and, if the answer is no, reuses what it already has. This negotiation uses validators. The server sends an ETag (a fingerprint of the content, RFC 9110 §8.8.3) or a Last-Modified (§8.8.2). On the next visit, the client returns those values in the conditional headers If-None-Match and If-Modified-Since (conditional requests, RFC 9110 §13; caching rules, RFC 9111).

# Primeira visita: o servidor devolve o recurso + um validador
GET /static/app.css HTTP/1.1
Host: exemplo.com

HTTP/1.1 200 OK
Content-Type: text/css
Content-Length: 46080
Cache-Control: max-age=0, must-revalidate
ETag: "9f8a1c-b3d0"
Last-Modified: Tue, 07 Jul 2026 10:00:00 GMT

...46080 bytes de CSS...

# Recarga: o cliente pergunta "mudou?" com o validador que guardou
GET /static/app.css HTTP/1.1
Host: exemplo.com
If-None-Match: "9f8a1c-b3d0"
If-Modified-Since: Tue, 07 Jul 2026 10:00:00 GMT

# Nada mudou -> resposta sem corpo
HTTP/1.1 304 Not Modified
ETag: "9f8a1c-b3d0"
Cache-Control: max-age=0, must-revalidate
Date: Wed, 08 Jul 2026 09:00:00 GMT

(sem corpo / no body)

Worked example #2: suppose a 45 KB CSS file, that is, 46,080 bytes (45 × 1,024). On the first visit, the client downloads the 46,080 bytes and stores the ETag "9f8a1c-b3d0". On reload, it sends If-None-Match with that value. If nothing changed, the server responds 304 returning only the headers, about 180 bytes, no body. Instead of 46,080 bytes, 180 travel: a saving of 45,900 bytes (46,080 − 180), or 99.6% (45,900 ÷ 46,080). Multiply that across dozens of resources per page and thousands of visits, and 304 becomes one of the web’s biggest performance levers.

Two details close the topic. First, a 304 never carries a body, if a proxy or framework returns content in a 304, something is wrong. Second, ETags come in two forms: strong (the content is byte-for-byte identical) and weak (a W/ prefix, the content is equivalent enough). The weak form helps when compression or whitespace vary without changing meaning. In both cases, it is the server that decides whether the validator still holds.

5xx: the other side failed, 500 vs 503, with 429 in the middle

In 5xx the problem is the server’s, but recognizing which code appeared points the debugging. The 500 Internal Server Error (§15.6.1) is the generic one, almost always an unhandled exception; the useful answer is in the log, not the number. The 502 Bad Gateway and 504 Gateway Timeout involve a proxy: 502 is an invalid response from the upstream service (the app crashed), 504 is the proxy getting no answer in time (the app hung). And the 503 Service Unavailable (§15.6.4) is the most honest of the family.

The practical difference between 503 and 500 is what the client should do. The 500 promises nothing, it could be a permanent bug. The 503 says “I’m down right now, come back later” and can attach the Retry-After header (RFC 9110 §10.2.3) telling you when to try again. That same header shows up in the 4xx cousin that signals excess: 429 Too Many Requests (RFC 6585 §4). When a rate limit is hit, a well-behaved server responds 429 and suggests in Retry-After how long to wait; a well-behaved client obeys before retrying.

Choosing the right code (and the curious corners)

Choosing the right status is a design decision, not a last-minute detail. The code is the first thing another system reads, a proxy, a crawler, a client deciding whether to retry. Getting it wrong is lying to whoever trusts that reading. This checklist settles most cases:

• Moved a plain page (GET) permanently? 301. Is it an API endpoint that receives POST? 308 (preserves the method).
• A passing detour? 302. If the method must survive, 307.
• Missing login/token? 401, and never forget the WWW-Authenticate header. Logged in but blocked? 403.
• A page that does not exist? 404. Removed on purpose? 410. Never 200 with “not found” in the body.
• Rate limit hit? 429 with Retry-After. Down for deploy/overload? 503 with Retry-After.
• Unexpected backend exception? 500, and go straight to the log. Cached resource might still be valid? Emit an ETag and answer 304 on revalidation.

Reading the status is just the start; the headers around it complete the story. Once the code is right, audit the rest of the response: the security headers analyzer grades your headers, the cookie inspector breaks down Set-Cookie flags, and the link checker vets a URL’s safety before you open it. Together, they turn “what number was that?” into “what is the whole response saying?”.