Start With One Sentence
A status code is not a human-readable annotation. It is a behavioural instruction shared by the client, the cache layer, and search engines. The cost of choosing wrong rarely shows up in logs; it shows up downstream: a POST downgraded to GET with the body dropped, ranking equity eaten by a temporary redirect, or a maintenance page returned as 200 and indexed as empty. The order of judgment is always the same: whose fault is it (4xx / 5xx) → did the resource move (3xx) → may the method and body change.
| Class | Meaning | Responsible party | First place to look |
|---|---|---|---|
| 1xx | Informational, request still in progress | Protocol layer | Usually no manual handling |
| 2xx | Success | Server | Body and headers complete? |
| 3xx | Resource moved | Server config | Location and redirect type |
| 4xx | Bad request | Caller | Parameters, credentials, URL |
| 5xx | Server failed to process | Server | Logs and downstream dependencies |
Quick Reference: When to Use It, and How It Is Misused
| Code | Use it when | Most common misuse |
|---|---|---|
| 100 | Pre-check before a large body (Expect: 100-continue) |
Returning it manually on normal endpoints; clients ignore it |
| 101 | WebSocket or protocol upgrade handshake | Returning it on ordinary business responses |
| 200 | Genuine success | Wrapping error content in 200 (soft 404 / soft 500) |
| 201 | Creation succeeded, with Location pointing at the new resource |
Returning 200 plus an id; callers cannot handle create uniformly |
| 204 | Success with provably no body (e.g. DELETE) | Using it when there is content; the client gets empty response.data |
| 206 | Range requests, resumable downloads, video seeking |
Ignoring Range yet returning 206; players parse fragments wrongly |
| 301 | Permanent page migration, HTTP to HTTPS, www normalisation | Using it for a temporary campaign — browsers cache it for a long time |
| 302 | Temporary redirect with legacy method semantics | Using it for a permanent migration; equity is not transferred |
| 304 | Conditional request hit the cache, no body | Sending a body anyway and wasting bandwidth |
| 307 | Temporary redirect that must preserve method and body | Mixing it up with 302; a POST silently becomes a GET |
| 308 | Permanent redirect that must preserve method and body (API) | Assuming it is always required for pages, ignoring browser differences |
| 400 | Malformed request or invalid parameter format | Returning 400 for server exceptions and database errors |
| 401 | Unauthenticated: missing or invalid credentials, must include WWW-Authenticate |
Returning 403 when the user is simply logged out |
| 403 | Authenticated but not permitted | Hiding existence inconsistently: 404 for one resource, 403 for another |
| 404 | Resource does not exist | Redirecting every unknown URL to the home page, creating soft 404s |
| 405 | Path exists but the method is not allowed; include Allow |
Omitting Allow, leaving callers guessing |
| 408 | The client did not finish sending in time | Confusing it with 504; 408 waits on the client, 504 waits on upstream |
| 409 | Conflict with current resource state (concurrent update, duplicate create) | Using 400 instead, so callers cannot distinguish bad input from bad state |
| 413 | Body exceeds the limit (typically uploads) | No client-side check, so users only see a failure |
| 429 | Rate limited; include Retry-After |
Limiting without telling the client when to retry, causing a retry storm |
| 500 | Uncaught exception | Returning 500 for validation failures and polluting alerts |
| 501 | The server does not support the feature or method | Confusing it with 405 |
| 502 | The gateway received an invalid upstream response (crash, not running) | Returning 500 when the backend is down and sending triage the wrong way |
| 503 | Overloaded or planned maintenance; include Retry-After |
Returning 200 for the maintenance page so it gets indexed as blank |
| 504 | The gateway timed out waiting for upstream | Treating it as the same thing as 502 |
| 511 | Network authentication required (captive portal) | Returning 403 on an internal portal, so the client cannot prompt |
Four Boundaries You Must Get Right
401 vs 403: authentication and authorisation are different jobs
401 answers "who are you"; 403 answers "what may you do". The distinction is not wording — it is input to client behaviour:
401withWWW-Authenticatetells the client to log in or refresh credentials.403tells the client that logging in again will not help, so it should stop prompting.
Returning 403 for "not logged in" destroys the reliable signal for redirecting to a login page; returning 401 for "no permission" triggers pointless credential-refresh loops. A 401 without WWW-Authenticate also violates RFC 9110, and some clients treat it as a protocol error.
Hiding resource existence is a separate concern: returning 404 to unauthorised users is a legitimate security choice, but be consistent for the same class of resource. Alternating between 403 and 404 leaks exactly the difference you were hiding.
301 / 302 / 307 / 308: method and equity have different traps
| Code | Permanent or temporary | Preserves method and body | SEO equity |
|---|---|---|---|
| 301 | Permanent | Not guaranteed (legacy implementations often turn POST into GET) | Transferred to the new URL |
| 302 | Temporary | Not guaranteed (same) | Stays with the original URL |
| 307 | Temporary | Mandatory | Stays with the original URL |
| 308 | Permanent | Mandatory | Transferred to the new URL |
Two practical conclusions:
- Use 301 for page migrations and 308 for API migrations. The former needs long-lived browser and crawler caching; the latter needs the method to survive. Using 302 for a permanent migration is the expensive mistake: the crawler treats the new URL as a temporary borrowing and leaves equity behind.
- Browsers cache 301, generally not 302. That is why a temporary campaign shipped with 301 cannot be rolled back cleanly — the redirect still lives in users' browsers.
Every extra hop costs a round trip, and some clients cap chain length. Point at the final target directly. When ERR_TOO_MANY_REDIRECTS appears, look for a cycle (A→B→A) first, then for a rule that redirects to itself.
404 / 410 / soft 404: three endings for a removed page
404means "not found now"; the resource may return.410means "permanently gone"; the semantics are explicit and crawlers usually drop it faster.- Soft 404 is a
200whose content says "not found" — the worst outcome, because the page stays indexable and users land on an empty shell.
Use 410 when content is retired for good; use 404 when it is temporarily unavailable or the replacement path is undecided. Do not 301 every unknown URL to the home page: crawlers classify that as a soft 404, and URLs that should disappear keep consuming crawl budget.
429 / 503 / 504: retry semantics decide what the other side does
All three say "not now", but they demand different actions:
429: you are asking too fast. Always sendRetry-After; without it, clients retry blindly and turn rate limiting into an avalanche.503: I cannot serve right now (overload or maintenance). WithRetry-After, crawlers treat it as temporary and come back later instead of penalising.504: upstream never answered. This is a link timeout, not rate limiting; the investigation belongs in downstream services and timeout settings.
The 502/504 split follows the same logic: 502 means an invalid upstream response arrived; 504 means no upstream response arrived at all. The first is usually a dead backend process or a non-HTTP reply; the second is usually an aggressive timeout or a slow query.
What Status Codes Actually Do to SEO
Only statuses a crawler remembers affect SEO:
| Response | Crawler behaviour | When to use |
|---|---|---|
| 200 | Crawled and indexed normally | Content genuinely available |
| 301 / 308 | Equity moves to the new URL; the old URL leaves the index | Permanent migration |
| 302 / 307 | Equity stays with the original URL; the new one is a temporary entry point | Short campaigns, A/B tests, staged rollout |
| 404 | Removed from the index, but more slowly | Temporarily unavailable or undecided |
| 410 | Explicitly gone; removed faster | Confirmed retirement |
| 5xx | URL retained, but sustained 5xx reduces crawl budget | Should only indicate an incident |
503 + Retry-After |
Treated as temporary; URL retained and retried later | Planned maintenance |
| 200 + "not found" | Classified as a soft 404, worse than a real 404 | Never |
Before shipping, check four things: no 302 on permanent migrations; no site-wide redirect of retired pages to the home page; maintenance returns 503, not 200; error pages do not all return 200. For the per-code reference, see the HTTP status code cheat sheet.
Triage: Assign Responsibility, Then Follow the Chain
- Class first. For 4xx, inspect the request — parameters,
Content-Type, credentials, URL encoding. For 5xx, inspect server logs and dependencies before touching the frontend. - Split the 5xx chain.
502means check the backend process and proxy configuration;504means check downstream timeouts and slow queries;500means look for uncaught exceptions;503means check load and maintenance state. - Common 4xx misreads.
400is usually aContent-Typeand body mismatch; for401, confirm the credential was actually sent (is there anAuthorizationheader in DevTools?); for403, separate insufficient role from WAF blocking; for404, verify routing and case before assuming deletion. - Find the source of a 429. Gateway limits, application limits, and third-party limits recover on different schedules; if
Retry-Afteris present, back off by it.
Monitor two numbers only: the 5xx rate (alert above 1%) and the Referer distribution of 404s, which exposes internal dead links directly. Both surface real incidents earlier than a full status-code census.
One Command to See What Is Really Returned
for p in / /reference /no-such-page-xyz; do
printf "%-22s %s\n" "$p" "$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:3100$p)"
done
/ 200
/reference 200
/no-such-page-xyz 404
-o /dev/null discards the body, -w '%{http_code}' prints only the status. When you need to know what a page actually returns, run this before guessing in the browser.