HTTP status codes: which one, and why

RFC 9110 says a 204 "cannot contain content". Node's http server drops a body you write with one, and a client that always parses JSON throws on it:

const res = await fetch("/api/cart/items/9", { method: "DELETE" }); // 204
await res.json(); // SyntaxError: Unexpected end of JSON input

Check res.status === 204 before parsing.

All four send the new URL in Location. Two questions pick the code:

The left column is history: browsers came to re-send a redirected POST as a GET, and RFC 9110 now allows it. The Fetch standard, which browsers and Node's fetch follow, does exactly that — after a 301 or 302, a POST becomes a body-less GET (other methods are kept). 307 and 308 exist to promise the method survives.

HTTP/1.1 308 Permanent Redirect
Location: /v2/uploads

For a GET, 301 and 308 behave alike, as do 302 and 307. For anything else, choose from the right column — or 303 when you want a GET (next card).

After a form POST succeeds, answer 303 with Location set to the result page. The browser follows with a GET, so the address bar shows /orders/42 and a refresh reloads that page instead of re-submitting the order.

HTTP/1.1 303 See Other
Location: /orders/42

303 means "the answer is over there — go GET it". The Fetch standard turns every method except GET and HEAD into GET on a 303 (PUT and DELETE too), where 302 only converts POST. That's also why 307 is wrong here: it would re-POST the form, body and all, to /orders/42.

RFC 9110 makes 301 and 308 heuristically cacheable: with no Cache-Control or Expires, a browser or CDN may store the redirect and follow it again without asking your server. Ship a wrong permanent redirect and clients that cached it keep going to the wrong place — the old URL is never requested, so your fix can't reach them until their copy expires or is cleared.

• Trying out a new redirect? Start with 302 or 307; switch to permanent once it's right.
• Want a permanent redirect you can still change? Give it an explicit lifetime:

HTTP/1.1 301 Moved Permanently
Location: https://example.com/docs/
Cache-Control: max-age=3600

302 and 307 are not heuristically cacheable: a client stores them only when you add caching headers.

A 304 answers a conditional GET or HEAD: the client holds a cached copy and asks for the resource only if it changed. If it hasn't, the server sends headers and no body, and the client reuses its copy.

GET /app.js HTTP/1.1
If-None-Match: "v42"

HTTP/1.1 304 Not Modified
ETag: "v42"

The validator came from an earlier 200: its ETag goes back in If-None-Match, its Last-Modified in If-Modified-Since. A 304 is not an error, and the 304s in the DevTools network panel are the cache working. When the browser's own cache made the request conditional, fetch hands your code the stored 200, not the 304.

• 400 Bad Request — the server can't or won't process the request as sent: malformed JSON, broken framing. The broad client-error fallback.
• 422 Unprocessable Content — the content type is understood (so not 415) and the syntax is correct, but the instructions can't be carried out. Valid JSON that breaks a rule:

{ "start": "2026-05-10", "end": "2026-05-01" }

422 came from WebDAV; RFC 9110 (2022) moved it into core HTTP and renamed it from "Unprocessable Entity". Both codes are used for validation errors — NestJS's ValidationPipe answers 400 by default, plenty of APIs use 422 — so pick one per API and keep it.

What's never right: letting a bad body surface as 500 because JSON.parse threw and nothing caught it.

• 401 Unauthorized — the request lacks valid credentials: no token, an expired one, a bad signature. Despite the name it means unauthenticated. The server must send WWW-Authenticate naming a scheme the client can use, and retrying with new credentials can succeed.
• 403 Forbidden — the server understood the request and refuses. If credentials were sent, they're valid but not enough: a signed-in non-admin calling an admin route. Re-sending the same credentials won't help, so a client shouldn't retry automatically.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer

Client rule of thumb: on 401, refresh the token or send the user to sign in; on 403, show "you don't have access" and keep the session.

• 404 Not Found — nothing here now. It says nothing about whether that's temporary or permanent.
• 410 Gone — it was here, it was removed on purpose, and it isn't coming back. It asks crawlers and link-checkers to drop their links. Use it only when you know the removal is permanent; otherwise 404.

RFC 9110 also lets a server answer 404 instead of 403 to hide that a resource exists. Answering 404 for another tenant's /invoices/981, exactly as for an id that doesn't exist, stops a caller from probing which ids are real.

Both codes are heuristically cacheable: without Cache-Control, a 404 for something created a minute later may still be served from a cache.

The URL exists, but not for this method: a POST /users/42 where only GET, PUT and DELETE are handled. RFC 9110 says a 405 must list what the resource does support:

HTTP/1.1 405 Method Not Allowed
Allow: GET, PUT, DELETE

Its neighbours:

• 404 Not Found — there's no such resource at all.
• 501 Not Implemented — the server doesn't recognise the method for any resource (a made-up BREW, say).

The request is well-formed, but it conflicts with the resource as it is now, and the client may be able to fix that and resubmit. Two everyday cases:

• Uniqueness: POST /users with an email that's already registered.
• Lost update: a PUT carrying "version": 7 when the stored record is at version 8 because someone else saved first.

RFC 9110 asks for enough detail to see what clashed:

{ "error": "version_conflict", "yourVersion": 7, "currentVersion": 8 }

If the version travels in an If-Match header instead of the body, the precise code is 412 Precondition Failed. And versus 422: a 422 body is wrong in itself; a 409 body would succeed against a different state.

The server won't take the body in the format it was sent: its Content-Type (or Content-Encoding) isn't one this endpoint accepts. The classic cause: curl -d labels its data application/x-www-form-urlencoded, even when the data is JSON.

curl -d '{"name":"Ada"}' https://api.example.com/users      # sent as a form
curl --json '{"name":"Ada"}' https://api.example.com/users  # sent as JSON (curl 7.82+)

Keep it apart from its neighbours:

• 406 Not Acceptable is about what the client asked to get back (Accept); 415 is about what it sent (Content-Type).
• 422 is the step after: format understood, contents wrong.

Defined in RFC 6585, not RFC 9110: this client sent too many requests in some window. The server decides how it counts — per user, per API key, per IP — and may say when to come back:

HTTP/1.1 429 Too Many Requests
Retry-After: 120

Retry-After is either a number of seconds or an HTTP date. A well-behaved client waits at least that long; a retry loop that ignores it just keeps hitting the limit. Caches must not store a 429.

Its neighbours: 503 is about the server, not this client's rate — it's temporarily unable to handle the request (overload, maintenance); 403 means the request is refused however slowly you send it.

A 500 means an unexpected condition stopped the server — typically an unhandled exception. It's the generic 5xx: use a more specific code when you know one (503 for overload, a 4xx when the client's input is the problem).

Two habits:

• Don't let bad input become a 500. A missing field that crashes body.name.trim() is a client error you didn't check for — validate it and answer 400 or 422.
• Don't send the stack trace. Log it with a request id and return a generic body:

{ "error": "internal_error", "requestId": "req_8f2c" }

5xx rates usually drive alerts and error budgets, so a client mistake reported as 500 pages your on-call engineer instead of telling the caller what to fix.

With a proxy, load balancer or CDN in front of your app, read these as where it broke:

When the app does send a proper error response, the proxy should pass it through, not replace it with a 502.

Not 408 Request Timeout: that's a server giving up on a client that didn't finish sending its request.