Skip to content
Velloreth
Web Development 10 min read

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

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?

ClassMeaningWho acts
1xxInformational, interim responseNobody — the real response follows
2xxSuccessThe client continues normally
3xxRedirectionThe client follows or the cache revalidates
4xxClient errorThe caller must change the request
5xxServer errorThe 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

SituationCode
Read succeeded200
Resource created201 + Location
Job queued202
Delete or update with nothing to return204
Resource moved forever308
Temporary redirect, method preserved307
Malformed request400
No or invalid credentials401 + WWW-Authenticate
Authenticated but not allowed403
Resource missing404
Verb not supported on this URL405 + Allow
Unique constraint or stale write409
Permanently removed410
Body too large413
Wrong content type415
Semantically invalid values422
Rate limited429 + Retry-After
Unhandled bug500
Upstream returned garbage502
Overloaded or in maintenance503 + Retry-After
Upstream never answered504

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.

Frequently asked questions

What is the difference between 401 and 403?
401 Unauthorized means the request lacks valid authentication credentials, so the client should authenticate and retry. 403 Forbidden means the server understood the request and knows who you are, but you are not allowed to do it, so retrying with the same credentials will never work.
Should an API return 404 or 204 when a list is empty?
Return 200 with an empty array. A 404 describes a missing resource, not an empty collection, and clients that treat 404 as an error will show a failure state for a perfectly healthy empty list.
Is 418 I'm a teapot a real status code?
It exists in the IANA registry as an April Fools' joke from RFC 2324, and many frameworks ship it. It has no defined behaviour in practice and should never appear in production responses.
Do HTTP status codes affect SEO?
Yes. Search engines use them to decide whether to index, drop, or keep a page: 200 means indexable, 404 and 410 mean drop it, and 301 passes ranking signals to the new URL while 302 does not.
What status code should a validation error return?
422 Unprocessable Content when the JSON parsed but the values are semantically invalid, or 400 Bad Request when the request itself is malformed. Return a machine-readable body listing each failing field.