HTTP status codes — the complete reference

How to read a status code you have never seen

The first digit is the whole answer to “whose problem is this?”. Everything after it is detail.

• 1xx — handshake traffic. A client library handles these; you will rarely see one in an application log.
• 2xx — it worked. The differences are about what the body contains and whether the client should change its view.
• 3xx — go somewhere else. The two things that matter are permanent versus temporary, and whether the method is allowed to change.
• 4xx — the request was wrong. Sending the identical request again will fail identically, so an automatic retry is pointless (with two exceptions: 408 and 429, which are about timing).
• 5xx — the server failed. The request may have been perfectly valid, so retrying an idempotent request with exponential backoff is the right behaviour.

The distinctions that cause real bugs

Pair	The difference	Getting it wrong causes
401 vs 403	“Who are you?” versus “I know, and no”	A token-refresh loop that can never succeed
400 vs 422	Unparseable versus parsed-but-invalid	Clients cannot tell a bug from a user-input error
301 vs 302	Permanent versus temporary	A mistaken 301 is cached by browsers for a very long time
302 vs 307	Method may change versus must not	A POST silently becomes a GET and the body vanishes
301 vs 308	Same, for permanent redirects	Same
404 vs 410	Not here versus deliberately gone	Search engines keep re-crawling a 404 for months
500 vs 503	Unhandled failure versus temporarily unavailable	Planned maintenance gets pages de-indexed
502 vs 504	Bad upstream response versus upstream too slow	You debug the wrong layer

Retry policy in one paragraph

Retry 408, 429, 500, 502, 503 and 504 — but only for idempotent requests (GET, HEAD, PUT, DELETE), or POSTs that carry an idempotency key. Honour Retry-After exactly when it is present. Otherwise back off exponentially with jitter, because synchronised retries from many clients turn a brief blip into a sustained outage. Cap the number of attempts, and never retry a 4xx other than those two.

Choosing status codes for your own API

1. Never return 200 with an error in the body. Every generic client, retry policy, cache and monitor keys off the status line.
2. Return 201 with a Location header when you create something.
3. Return 204 with no body for a successful delete, and remember that a 204 must not have a body at all.
4. Put machine-readable detail in the body — RFC 9457’s application/problem+json is a good default — and keep the status code coarse.
5. Include Retry-After on every 429 and 503. It is the one header clients genuinely act on.

Sources

The definitions here follow RFC 9110 (HTTP Semantics) and the extension RFCs cited on each code’s page, cross-checked against the IANA HTTP Status Code Registry. The causes and fixes are practitioner notes rather than part of any specification, and vendor-specific codes are marked as such so nothing here implies they are standard.