LineLapse BlogMake your own →
← All posts

The HTTP status codes you actually need

#http#networking#web#apis

There are more than 60 official HTTP status codes, and most engineers spend a career using about a dozen of them. The rest exist for edge cases nobody hits twice. Here's the small set that actually shows up in server logs, API docs, and 2am incident channels — grouped so the pattern sticks.

HTTP Status Codes You Actually Need5 families · 15 codesFive Families1xxInformationalstill thinking2xxSuccess✓ happy path3xxRedirectiongo elsewhere4xxClient erroryour fault5xxServer errortheir faultfirst digit = shelf2xx Success200OKrequest worked, here's data201CreatedPOST succeeded, resource made204No Contentsuccess, nothing to return201 → Location headerstart here! ✓3xx Redirect301Moved Permanentlycached forever — update links302Foundtemporary detour, not cached304Not Modifiedbrowser has fresh copy, no body sentsaves bandwidth4xx Client Errors400Bad Requestserver can't parse what you sent401Unauthorizedyou need to log in403Forbiddenlogged in but still not allowed404Not Foundthe famous one422Unprocessable Entitydata shape is wrong (APIs)your fault5xx Server Errors500Internal Server Errorcatch-all crash502Bad Gatewayproxy got broken upstream response503Service Unavailablealive but overwhelmed or in maintenancetheir faulton-call nightmareThe #1 API Trap// ❌ NEVER do thisHTTP 200 OK{ "error": "something failed" }// ✅ Use the right status codeHTTP 422 Unprocessable Entitythe #1 mistakePin These Rules4xx = your fault · 5xx = their fault301 permanent & cached · 302 temporary & not201 Created must include a Location header304 sends no body — that's the whole pointnever 200 OK with an error inside the bodypin this15 codes · read logs natively
▶ Watch it draw

The first digit is the headline

Before memorizing individual codes, know the five families. The first digit tells you the category of what happened, and you can often guess the right response just from that:

  • 1xx — informational. The request is still in progress. You'll rarely see these directly; they're mostly handled by the networking layer beneath your code.
  • 2xx — success. The request worked.
  • 3xx — redirection. The resource moved, or the client already has a valid copy.
  • 4xx — client error. The request was wrong somehow — bad input, missing auth, a URL that doesn't exist.
  • 5xx — server error. The request was fine; the server broke while handling it.

That split matters operationally, too: a spike in 4xx usually means a client bug or an API change nobody announced, while a spike in 5xx means your system is unhealthy. Alerting on the two separately catches different problems.

Success: 200, 201, 204

200 OK is the default success response and covers most GET requests. 201 Created is more specific — use it when a POST successfully creates a new resource, and pair it with a Location header pointing at the new thing. 204 No Content means the request succeeded but there's nothing to send back, which is exactly the shape of a successful DELETE.

Using 201 and 204 instead of a blanket 200 everywhere isn't pedantry — it lets clients and monitoring tools tell "created" and "deleted" apart from "fetched" without parsing the response body.

Client errors: 400, 401, 403, 404, 409, 429

400 Bad Request is the catch-all for "I can't even parse what you sent me" — malformed JSON, a missing required field. 401 Unauthorized means you haven't proven who you are (despite the name, it's really about authentication). 403 Forbidden means you're known, but not allowed — authorization, not authentication. Mixing up 401 and 403 is one of the most common API mistakes, and the fix is a one-line rule: no valid credentials at all → 401; valid credentials that just lack permission → 403.

404 Not Found is the one everyone knows. 409 Conflict is the underused one — it's for a request that's individually valid but clashes with the current state, like two people editing the same record at once. 429 Too Many Requests is how a well-behaved API tells you to slow down, usually with a Retry-After header telling you exactly how long.

Server errors: 500, 502, 503, 504

500 Internal Server Error is the generic "something broke in our code" response — an unhandled exception, essentially. The next three are about infrastructure between the client and your actual application logic: 502 Bad Gateway means a proxy or load balancer got an invalid response from the server behind it; 503 Service Unavailable means the server is up but can't handle the request right now (overloaded, or deliberately down for maintenance); 504 Gateway Timeout means the upstream server took too long to respond at all. If you're debugging a 502 or 504, the bug is often in a different service than the one that returned the error.

Redirects, briefly: 301, 302, 304

301 Moved Permanently tells clients (and search engines) to update their bookmarks — the new location is the real one now. 302 Found is a temporary redirect; keep using the original URL next time. 304 Not Modified is the quiet workhorse of caching: the client already has a valid copy, and the server is just confirming nothing changed, saving a full re-download.

The takeaway

Status codes are a contract, not decoration. A client shouldn't have to parse your response body to know whether something succeeded, and a monitoring dashboard shouldn't have to guess whether a spike is your fault or theirs. Get the family right first — 2xx, 4xx, or 5xx — and the specific code usually follows naturally from what actually happened.

This explainer was made with LineLapse — type a topic, get a hand-drawn cheat sheet. Make your own →