HTTP Status Codes

How to read a status code at a glance

Every HTTP response carries a three-digit status code, and the first digit alone tells you the category of what happened. Memorize the five classes and you can diagnose most issues without looking anything up:

The single most useful instinct this gives you: a 4xx means look at what you sent (bad URL, missing auth, malformed body), while a 5xx means look at the server (check its logs). This reference lists every standard code in those classes, and you can filter by class tab or search by number or keyword; clicking any code copies it to your clipboard.

The pairs developers confuse most

301 vs 302 vs 307/308

301 Moved Permanently tells browsers and search engines the resource has a new home for good — they update bookmarks and cache the redirect. 302 Found is temporary; clients keep using the original URL next time. The subtle trap is that 301 and 302 historically let clients change a POST into a GET on redirect. When you must preserve the HTTP method, use 307 Temporary Redirect or 308 Permanent Redirect instead — they are the method-preserving equivalents, so a redirected POST stays a POST.

401 vs 403

401 Unauthorized actually means unauthenticated: the server doesn't know who you are because credentials are missing or invalid — log in. 403 Forbidden means the server knows exactly who you are and is refusing anyway — you lack permission, and re-authenticating won't help. If you're getting 401 after logging in, your token isn't reaching the server; if you're getting 403, your account simply isn't allowed.

404 vs 410

Both say "not here," but 404 Not Found is non-committal — the resource may appear later. 410 Gone is a deliberate, permanent statement that it existed and was removed for good, which signals search engines to drop the URL faster than a 404 would.

A worked example: tracing a real request

Suppose you POST a sign-up form to /api/users. A healthy flow returns 201 Created with a Location header pointing at the new record — note that successful creation is 201, not a plain 200. Now suppose the email is already taken: a well-built API returns 409 Conflict (the request clashes with current state) or 422 Unprocessable Content (the JSON was valid but failed a business rule). If you instead see 400 Bad Request, your JSON itself is malformed. A 429 Too Many Requests means you tripped a rate limit — back off and retry later. And a 500 Internal Server Error means your request was fine but the server threw an unhandled exception; the fix lives in the server logs, not your client.

Codes worth knowing that people forget

• 204 No Content — success with nothing to return, the right answer for a DELETE.
• 206 Partial Content — the server sent a byte range; this is how video seeking and resumable downloads work.
• 304 Not Modified — your cached copy is still good, so no body is sent. Essential for performance, and easy to mistake for an error when reading logs.
• 418 I'm a Teapot — a genuine, officially registered code from an April Fools' RFC, occasionally used as a playful rejection.
• 451 Unavailable For Legal Reasons — content blocked by law or court order, its number a nod to Fahrenheit 451.
• 503 Service Unavailable vs 502 Bad Gateway — 503 means the server is up but overloaded or in maintenance; 502 means a proxy got a broken reply from an upstream service behind it.

Common mistakes when choosing a code

• Returning 200 for everything. Wrapping errors in a 200 with an {"error": ...} body breaks caching, monitoring, and client libraries that branch on status. Use the right class.
• Using 401 when you mean 403. Sending 401 to an authenticated-but-unauthorized user invites pointless re-login loops.
• Treating 3xx as failures. Redirects are normal; a 301 in your logs usually means things are working, not breaking.
• Reaching for 500 on bad input. If the caller sent something wrong, that's a 4xx. Reserve 5xx for genuine server-side faults so you can actually trust your error dashboards.