HTTP Status Codes Explained: Practical Reference 2026
Every HTTP status code that matters in practice, which one your API should actually return, and the mistakes that cause confusing client and server bugs.
By Velloreth
What an HTTP status code actually is
An HTTP status code is a three-digit integer returned in the status line of every HTTP response, and it is the only part of the response that infrastructure is guaranteed to understand. A proxy, a CDN, a retry library, a load balancer, and a browser all read that number. Almost none of them read your JSON error body.
The first digit is the class, and the class answers one question: who should act next?
| Class | Meaning | Who acts |
|---|---|---|
| 1xx | Informational, interim response | Nobody — the real response follows |
| 2xx | Success | The client continues normally |
| 3xx | Redirection | The client follows or the cache revalidates |
| 4xx | Client error | The caller must change the request |
| 5xx | Server error | The server must be fixed; the caller may retry |
The current authoritative definition is RFC 9110, which replaced the older RFC 7231 in 2022. The registry is maintained by IANA, and new codes appear there occasionally — 103 Early Hints and 425 Too Early are both modern additions.
That is the whole theory. The rest of this article is about the decisions you actually have to make.
The 4xx versus 5xx line matters more than the exact code
If you remember one rule, make it this one: 4xx means do not retry, 5xx means retrying might work.
This is not a style preference. Retry middleware in most HTTP clients is configured to retry 5xx and network failures with exponential backoff, and to abandon 4xx immediately. Circuit breakers open on 5xx rates. Uptime monitors alert on 5xx. If you return a 500 for a user who sent a malformed email address, you have just paged yourself at 3 a.m. for a client-side bug.
Conversely, if you return a 400 when your own database connection pool is exhausted, you have just told every client to give up permanently on a transient problem — and told your monitoring that everything is fine.
A useful test: if the same request were sent again unchanged and the server were healthy, would it succeed? If yes, it is a 5xx. If no, it is a 4xx.
2xx: the success codes worth using
200 OK is the default. It carries a body and means the request worked.
201 Created belongs on POST endpoints that create a resource. It should include a Location header pointing at the new resource. Clients that distinguish 201 from 200 will follow that header; returning 200 forces them to parse your body to find the ID.
202 Accepted means the request was valid but processing is asynchronous. This is the honest code for a job queue. Returning 200 with a status: "pending" body is technically fine but tells the client nothing about the fact that they need to poll.
204 No Content means success with nothing to say — the correct response for a DELETE, or for a PUT that does not return the updated object. The body must be empty; a 204 with a body is a protocol violation that some HTTP clients reject outright.
206 Partial Content is what makes video seeking and resumable downloads work. You get it by handling Range headers, not by choosing it.
3xx: redirection is a caching instruction
The 3xx codes are where search-engine behaviour and cache behaviour collide, so they deserve more care than they usually get.
301 Moved Permanently — the resource has a new home, and clients may cache this decision indefinitely. Search engines transfer ranking signals to the target. Use it when a URL is truly gone for good.
308 Permanent Redirect — the same as 301, but the method and body are preserved. A 301 historically allowed clients to change POST to GET; a 308 forbids that. For an API, prefer 308.
302 Found — temporary. Clients must not cache it. Because of the historical POST-to-GET behaviour, it is a poor choice for anything that is not a GET.
307 Temporary Redirect — temporary, with the method preserved. This is the correct temporary redirect for non-GET requests.
304 Not Modified — the client’s cached copy is still valid; send no body. This is the payoff of ETag and If-None-Match, and it is a large part of why static sites feel fast. If you want the longer version of how this interacts with edge caching, how CDNs actually work covers the mechanics.
308 vs 301 and 302 vs 307 is the pair people mix up. The rule: the modern, method-preserving variants are 307 and 308; the legacy, method-mutating ones are 301 and 302.
4xx: the codes that describe client mistakes
400 Bad Request — the request is structurally wrong: malformed JSON, a missing required field, a header that cannot be parsed. It is the correct default when you cannot be more specific.
401 Unauthorized — a misleading name. It means unauthenticated: no credentials, or credentials that did not validate. It must include a WWW-Authenticate header. The client’s correct response is to authenticate and try again, not to give up.
403 Forbidden — authenticated, but not permitted. This is the distinction interviewers love and production code often gets wrong. If a user’s token is valid but their role cannot delete the record, that is 403, not 401. Retrying with the same token will never work.
404 Not Found — the resource does not exist, or you are deliberately hiding its existence from someone who is not allowed to see it. Using 404 instead of 403 to avoid leaking the existence of private records is a legitimate, common choice.
405 Method Not Allowed — the URL exists but not for this verb. It must include an Allow header listing the verbs that do work.
409 Conflict — the request conflicts with current state. The classic cases are creating a record whose unique field already exists, and optimistic concurrency failures where an If-Match ETag no longer matches. This is the correct code for a lost update, and it is much better than a generic 400 because the client knows the fix is to re-read and retry.
410 Gone — permanently removed, and you know it. Unlike 404, 410 tells crawlers they can drop the URL rather than keep checking.
412 Precondition Failed — a conditional header failed. Related to 409 but specific to If-Match and If-Unmodified-Since.
413 Content Too Large — the body exceeds your limit. Worth implementing explicitly, because a reverse proxy will otherwise reject it before your application ever sees it, usually with a less helpful message.
415 Unsupported Media Type — the Content-Type is not one you accept. Distinct from 400: the request is well-formed, just in the wrong format.
422 Unprocessable Content — the request parsed correctly but the values are semantically invalid. This is the best code for form validation failures, and returning it with a per-field error list is a large usability win. The pattern of returning structured field errors is worth designing once and reusing — form validation patterns covers the client side of the same contract.
429 Too Many Requests — rate limited. Always pair it with Retry-After, either as seconds or an HTTP date. A 429 without Retry-After forces clients to guess, and guessing clients retry in a tight loop that makes the problem worse. If you are designing the limiter itself, rate limiting for REST APIs goes deeper.
5xx: the codes that describe your bugs
500 Internal Server Error — an unhandled exception reached the top. It should be rare and alarming. A 500 in a metrics dashboard should mean a real bug, not a user typing a bad character.
501 Not Implemented — you do not support this method at all, ever. Rare in practice; most “not implemented” cases should be 405.
502 Bad Gateway — an upstream service returned something unusable. This is the code you see when your app is fine but the service it calls is not.
503 Service Unavailable — temporarily unable to handle the request, usually overload or maintenance. A Retry-After header is welcome here too.
504 Gateway Timeout — an upstream did not respond in time. The distinction from 502 is that 502 got a bad answer and 504 got no answer.
A practical note: 502 and 504 are almost always infrastructure, not application code. When you see them after a deploy, look at the proxy or the platform before you look at your handler. This is exactly the kind of signal-versus-noise problem that debugging strategies that work is about.
The five status-code mistakes that cause real damage
1. Returning 200 with an error body. This is the worst one. Every system in the chain — retries, caching, monitoring, alerting, and the browser — believes the request succeeded. A cache may even store the error response and serve it to other users. If there is one thing to fix in an existing API, it is this.
2. Using 500 for client errors. It inflates your error rate, pages the wrong person, and tells clients to retry something that will never work.
3. Using 400 for everything. It is not wrong, exactly, but it discards information the client could have acted on. A 409, 422, or 429 each tell the caller something specific and useful.
4. Forgetting Retry-After on 429 and 503. The header is what turns a rate limit from a wall into a schedule.
5. Inconsistent codes across endpoints. If POST /users returns 201 on success but POST /orders returns 200, every client integration has to special-case both. Pick a convention and write it down.
Debugging a status code you did not expect
When a response comes back with a code you did not write, work outward from the client:
curl -sS -o /dev/null -D - https://example.com/api/orders
-D - dumps the response headers to stdout, which shows you the status line, any Location, and any Retry-After in one shot. Most confusion about status codes turns out to be a proxy or CDN rewriting the response, and the headers usually say so.
For a full request trace including redirects, add -L and -v — the verbose output shows each hop’s status separately, which is the only reliable way to see that a 200 was actually a 301 followed by a 200.
If you are rendering pages rather than APIs, remember that a status code also affects how the page is indexed — a soft 404, where you return 200 for a missing page, is a real ranking problem. The Astro SEO checklist walks through the canonical and status-code side of that.
A short reference for choosing a code
| Situation | Code |
|---|---|
| Read succeeded | 200 |
| Resource created | 201 + Location |
| Job queued | 202 |
| Delete or update with nothing to return | 204 |
| Resource moved forever | 308 |
| Temporary redirect, method preserved | 307 |
| Malformed request | 400 |
| No or invalid credentials | 401 + WWW-Authenticate |
| Authenticated but not allowed | 403 |
| Resource missing | 404 |
| Verb not supported on this URL | 405 + Allow |
| Unique constraint or stale write | 409 |
| Permanently removed | 410 |
| Body too large | 413 |
| Wrong content type | 415 |
| Semantically invalid values | 422 |
| Rate limited | 429 + Retry-After |
| Unhandled bug | 500 |
| Upstream returned garbage | 502 |
| Overloaded or in maintenance | 503 + Retry-After |
| Upstream never answered | 504 |
Why this is worth the five minutes
Status codes are the narrowest interface in your entire stack, and every layer between the client and your database speaks it. Getting them right costs almost nothing at design time and saves an enormous amount of debugging later, because the code is the one piece of information every tool down the chain is guaranteed to read correctly.
The single highest-value change, for almost any API: stop returning 200 for failure, and stop returning 500 for a bad request. Everything else is refinement.