HTTP Status Codes

How status code classes work

Every HTTP response starts with a three-digit code, and the first digit tells you who to blame. 1xx codes are informational interim responses (you'll mostly meet 101 during WebSocket upgrades). 2xx means success — usually 200, with 201 for creations and 204 for deliberate empty bodies. 3xx redirects the client elsewhere; the distinctions between 301, 302, 307 and 308 come down to whether the move is permanent and whether the HTTP method must be preserved. 4xx says the client did something wrong — a bad URL (404), missing auth (401), insufficient permission (403) or too many requests (429). 5xx says the server failed: an unhandled exception (500), a dead upstream behind a proxy (502) or a slow one (504). Getting the class right matters beyond pedantry — retry logic, caching, monitoring alerts and search engines all key off it.

The confusions that cause real bugs

A handful of pairs account for most status-code mistakes. 401 vs 403: 401 means "I don't know who you are — authenticate", 403 means "I know exactly who you are, and the answer is no"; retrying with credentials fixes the first, never the second. 502 vs 504: both come from a proxy, but 502 means the upstream returned garbage or refused the connection (it's probably down), while 504 means it accepted the request and never answered in time (it's probably hung or slow). 301 vs 302: browsers cache 301s aggressively, so shipping a wrong permanent redirect can haunt users long after you fix it — test moves with 302 first. And 404 vs 410: both mean "not here", but 410 tells search engines the removal is deliberate and permanent, so they de-index faster.

FAQ

Is 418 "I'm a teapot" a real status code?

Yes and no. It was defined in RFC 2324 — the Hyper Text Coffee Pot Control Protocol, an April Fools' joke from 1998 — so it's not part of the real HTTP spec. But it's implemented in most major frameworks, and when the IETF tried to reclaim the code in 2017 the internet campaigned to save it. Some services genuinely return it for playful request blocking.

Why does my API return 200 even when something failed?

Because some backends wrap every result in a 200 and put the real outcome in the JSON body — a pattern common with older RPC-style APIs and some GraphQL servers. It works, but it blinds HTTP-level tooling: monitoring, retry middleware, caches and load balancers all assume the status code tells the truth. If you control the API, prefer real 4xx/5xx codes.

Which status codes should my client retry?

Safe bets: 429 (honor the Retry-After header), 503 and 504 — all signal transient conditions. 502 is usually worth a couple of retries with backoff. Never blindly retry 4xx codes other than 429/408 — the request itself is wrong and will fail identically every time.