HTTP Status Codes

The class digit carries the contract

Every HTTP response begins with a three-digit code, and the first digit is the only part a client is required to understand. RFC 9110 is explicit about this: a client that receives an unrecognised 499 must treat it exactly like a 400, because the class defines the semantics and the remaining two digits only refine them. That rule is what keeps the protocol extensible. A proxy written in 2005 can still route a 451 correctly without knowing what legal censorship is.

The five classes divide cleanly by who is responsible for what happens next. A 1xx is an interim response, so the real answer is still coming and the connection stays open. A 2xx means the request succeeded and the client can stop. A 3xx hands back a redirect, so the client should try again somewhere else. A 4xx blames the request, so repeating it unchanged will fail again. A 5xx blames the server, so the identical request might succeed on retry. This is why retry logic keys off the class rather than the specific code: retrying a 503 is reasonable, retrying a 403 is a bug.

Codes that are routinely confused

The distinction between 301 and 308, or 302 and 307, is not stylistic. The older pair permits a client to rewrite a POST into a GET when it follows the redirect, which browsers have historically done. The newer pair forbids that rewrite and preserves both the method and the body. If you move a form endpoint with a 301, some clients will silently convert the submission to a GET and drop the payload. Use 308 or 307 for anything that is not idempotent.

401 and 403 are similarly mixed up. A 401 means the request was not authenticated and must arrive with a WWW-Authenticate challenge, telling the client how to try again with credentials. A 403 means the server understood who you are and is still refusing. Sending a 401 with no challenge header is a specification violation, and sending a 403 when the user simply forgot to log in makes the failure much harder to debug.

The 4xx class also holds a genuinely useful pair: 400 versus 422. A 400 means the request could not be parsed at all, so the syntax is broken. A 422 means the syntax parsed fine but the content failed validation. Splitting those two turns an opaque failure into an actionable one for API clients.

Reason phrases are for humans only

The text beside the code, such as Not Found or I'm a teapot, is the reason phrase. HTTP/1.1 sends it on the status line, but HTTP/2 and HTTP/3 removed it entirely, so a modern connection often carries the number with no phrase at all. Nothing in a client should ever branch on that string. It exists so that a human reading a log or a raw trace can see what happened without a lookup table.

Some codes are also more constrained than they look. A 204 and a 304 must not include a message body, so an intermediary that adds one is producing an invalid response. A HEAD response never carries a body regardless of code. These framing rules matter because a body where none is expected desynchronises connection reuse, which surfaces as bizarre cross-request corruption rather than an obvious error.