HTTP Status Codes
The response codes worth memorizing, grouped by class, with when to use each.
Every HTTP response starts with a three-digit status code, and the first digit is the class: 1xx informational, 2xx success, 3xx redirection, 4xx the client’s fault, 5xx the server’s fault. Clients, proxies, caches and crawlers act on the class even when they do not know the exact code, so the right choice changes real behavior — whether a request is retried, cached or indexed.
Names follow RFC 9110, the current HTTP semantics standard. Pair every error code with a body that explains it: the code is for machines, the message is for people.
x00 of its class. The highlighted codes are the ones a well-behaved client retries, with backoff.1xx — Informational
- 100 Continue
- go ahead and send the body — the reply to
Expect: 100-continue - 101 Switching Protocols
- protocol upgrade accepted — how a WebSocket connection starts
- 103 Early Hints
- preload
Linkheaders sent before the real response is ready
2xx — Success
- 200 OK
- Standard success with a body
- 201 Created
- A resource was created (return its location)
- 202 Accepted
- Accepted for async processing
- 204 No Content
- Success, nothing to return
- 206 Partial Content
- a
Rangerequest served — video seeking, resumable downloads
3xx — Redirect
- 301 Moved Permanently
- Permanent new URL (SEO-safe)
- 302 Found
- Temporary redirect
- 304 Not Modified
- Use your cached copy
- 303 See Other
- after a POST, send the client to a GET page — Post/Redirect/Get
- 307 Temporary Redirect
- like 302, but the method and body must not change
- 308 Permanent Redirect
- like 301, but the method and body must not change
4xx — Client error
- 400 Bad Request
- Malformed request
- 401 Unauthorized
- Not authenticated
- 403 Forbidden
- Authenticated but not allowed
- 404 Not Found
- No such resource
- 409 Conflict
- State conflict (e.g. version clash)
- 422 Unprocessable Content
- Valid syntax, failed validation
- 429 Too Many Requests
- Rate limited — back off
- 405 Method Not Allowed
- the URL exists but not for this method; send an
Allowheader - 410 Gone
- deliberately removed for good — crawlers drop it faster than a 404
- 412 Precondition Failed
If-MatchorIf-Unmodified-Sincedid not hold: blocks lost updates- 413 Content Too Large
- request body over the server’s limit (formerly “Payload Too Large”)
- 415 Unsupported Media Type
- the body’s
Content-Typeis not one the endpoint accepts
4xx — Less common
- 406 Not Acceptable
- nothing matches the client’s
Acceptheaders - 408 Request Timeout
- the client took too long to send the request; safe to retry
- 414 URI Too Long
- usually a GET carrying data that belongs in a POST body
- 416 Range Not Satisfiable
- the requested byte range lies outside the file
- 418 I’m a teapot
- an April Fools’ joke from RFC 2324 — keep it out of real APIs
- 425 Too Early
- the server refuses to process TLS early data that could be replayed
- 428 Precondition Required
- the server demands a conditional request, such as
If-Match - 431 Request Header Fields Too Large
- headers too big — very often an overgrown cookie
- 451 Unavailable For Legal Reasons
- blocked by a legal demand such as a court order
5xx — Server error
- 500 Internal Server Error
- Unhandled failure
- 502 Bad Gateway
- Upstream returned garbage
- 503 Service Unavailable
- Overloaded or down — retry later
- 504 Gateway Timeout
- Upstream too slow
- 501 Not Implemented
- the server does not support the method at all, for any resource
- 505 HTTP Version Not Supported
- the request’s HTTP version is refused
- 511 Network Authentication Required
- a captive portal (hotel or airport Wi-Fi) wants you to log in first
Non-standard (seen in logs)
- 499 (nginx)
- the client closed the connection before the response — often a client-side timeout
- 444 (nginx)
- nginx closed the connection without sending any response
- 520 (Cloudflare)
- the origin returned an empty or unexpected response
- 522 (Cloudflare)
- the TCP connection to the origin timed out
- 524 (Cloudflare)
- the origin accepted the connection but sent no response within 100 seconds
Choosing the right code
- 401 vs 403
- 401: credentials missing or invalid (send
WWW-Authenticate); 403: known caller, still no - 400 vs 422
- 400: cannot parse the request; 422: parsed fine, but fails validation rules
- 404 vs 410
- 404: not here, may come back; 410: removed on purpose, for good
- 404 instead of 403
- hide whether a resource exists from callers not allowed to know
- 301/302 vs 308/307
- 301 and 302 let clients turn a POST into a GET; 308 and 307 forbid it
- 409 vs 412
- 409: the state conflicts (duplicate, wrong status); 412: the sent ETag is stale
- Retry-After
- with 429 or 503: seconds or an HTTP date telling clients when to come back
- 202 + Location
- job accepted; point at a status URL the client can poll
- 500 vs 503
- 500 is a bug; 503 is a known temporary state such as overload or maintenance
Worked example: every status code in one upload API
An API takes video uploads, transcodes them in the background and serves the result. Follow one client through it:
POST /videos Content-Type: text/plain -> 415 Unsupported Media Type
POST /videos 3 GB body, limit is 2 GB -> 413 Content Too Large
POST /videos valid mp4 -> 202 Accepted
Location: /jobs/81
GET /jobs/81 still running -> 200 OK {"state":"transcoding"}
GET /jobs/81 finished -> 303 See Other
Location: /videos/7
GET /videos/7 -> 200 OK ETag: "a1"
GET /videos/7/file Range: bytes=0-1048575 -> 206 Partial Content
GET /videos/7 If-None-Match: "a1" -> 304 Not Modified
DELETE /videos/7 -> 204 No Content
GET /videos/7 -> 410 Gone
- 415, then 413. Both are the client’s problem and neither is worth retrying unchanged. A client that sends
Expect: 100-continuelearns about the 413 from the headers alone, before it uploads 3 GB. - 202 with a Location. Transcoding takes minutes, so the server accepts the job and points at a status URL instead of holding the connection open.
- 200 while running, then 303. The job resource itself exists, so polling it is a success. When it finishes, 303 sends the client to the new video with a GET.
- 206 and 304. A player seeks by asking for byte ranges; a revisit with the stored ETag costs headers only, not the video.
- 204, then 410. The delete succeeded with nothing to return. Answering 410 afterwards requires remembering that the ID existed; if you keep no record, 404 is the honest answer.
Recipes
Check status codes and redirects from the shell
curl -s -o /dev/null -w '%{http_code}\n' https://example.com # just the code: 200
curl -sI https://example.com | head -1 # status line: HTTP/2 200
curl -sIL http://github.com | grep -iE '^(HTTP|location)' # every redirect hop
# HTTP/1.1 301 Moved Permanently
# Location: https://github.com/
# HTTP/2 200-I sends HEAD, and a few servers answer HEAD differently from GET; use -s -o /dev/null -w with a normal GET when the difference matters.
A conditional GET that returns 304
curl -sI https://code.jquery.com/jquery-3.7.1.min.js | grep -i etag
# etag: "28feccc0-155ed"
curl -sI -H 'If-None-Match: "28feccc0-155ed"' https://code.jquery.com/jquery-3.7.1.min.js | head -1
# HTTP/2 304 <- no body sent: the cached copy is still currentThe quotes are part of the ETag value and must be sent back exactly. A 304 saves the body transfer, not the round trip — Cache-Control: max-age is what skips the request entirely.
Optimistic concurrency with If-Match
GET /docs/7 -> 200, ETag: "v3"
PUT /docs/7 (If-Match: "v3")
nobody else saved -> 200 OK, new ETag "v4"
someone saved first -> 412 Precondition Failed: re-fetch, merge, retry
PUT /docs/7 (no If-Match header) -> 428 Precondition Required, if the server insistsThis stops two editors silently overwriting each other. Use 409 instead when the conflict is about business state, such as cancelling an order that has already shipped.
Retry rules for an API client
retry: 408, 429, 500, 502, 503, 504, and network errors
honor: Retry-After on 429 and 503 (seconds or an HTTP date)
back off: exponential with jitter, e.g. sleep(random(0, base * 2 ** attempt))
give up: 400, 401, 403, 404, 409, 422 — the same request will fail again
careful: retry POST only with an idempotency key, or the action may run twiceJitter spreads retries out so a fleet of clients does not hammer a recovering server in lockstep. Cap both the attempts and the total time.
Map API errors to status codes
body is not valid JSON -> 400 Bad Request
valid JSON, but "email" is missing -> 422 Unprocessable Content
no token, or the token expired -> 401 Unauthorized (+ WWW-Authenticate)
valid token, but someone else's order -> 404 Not Found (or 403)
order already shipped, cannot cancel -> 409 Conflict
too many requests from this API key -> 429 Too Many Requests (+ Retry-After)
database unreachable -> 503 Service Unavailable
unexpected exception -> 500 Internal Server ErrorReturning 404 for objects the caller may not see avoids confirming that an ID exists. Whatever you choose, document it and use it the same way on every endpoint.
When to use it, and when not
Use the most specific standard code whose meaning a client can act on, because generic software acts on codes without reading your body: browsers follow 3xx, caches store some responses by default, crawlers drop a 410 faster than a 404, and retry libraries retry 503 but not 400.
- Fall back to the class when no specific code fits. 400 and 500 are always correct for their class, just less informative.
- Do not reuse a code for a different meaning or invent new ones. Put the detail in the body, for example as an RFC 9457 problem details object with a
typeand a readabledetail. - Not every empty answer is an error. A search with no matches is 200 with an empty list; 404 means the resource at that URL does not exist.
Trade-offs and limits
| Choice | Gives you | Costs |
|---|---|---|
| 301 instead of 302 | clients and search engines update to the new URL | browsers cache it, so a mistaken 301 keeps redirecting users after you remove it |
| 404 instead of 403 | callers cannot probe which IDs exist | harder debugging for legitimate users with the wrong role |
| 422 alongside 400 | clients can tell parse errors from rule errors | one more code to document and handle |
| 200 with an error body | nothing in the path needs to understand HTTP | monitoring, caches and retry logic all see a success |
Caching follows from the code. Without explicit freshness headers, RFC 9110 lets caches store 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414 and 501 heuristically, so a CDN can keep serving a 404 for a page you have since published. Send Cache-Control on error responses you do not want remembered.
Common mistakes
- 200 with an error in the body.
{"ok": false}under a 200 hides the failure from dashboards, alerting and every retry library, and a cache may store it as a good answer. - A permanent redirect you were not sure about. Browsers cache 301 and 308, so a wrong one lingers on users’ machines. Test with 302 or 307, then switch.
- 500 for bad input. An unhandled parse error on malformed JSON surfaces as 500, so clients retry a request that can never succeed and your alerts fire for someone else’s bug. Validate and answer 400 or 422.
- Soft 404s. A “page not found” template served with 200 gets crawled and can be indexed as a real page. Send the 404 status with the friendly page.
- 403 for rate limiting. Clients treat 403 as final and give up or alert. 429 with
Retry-Aftertells them to slow down and when to come back.
Check yourself
A form is submitted with POST and the response is 307 to /done. What does the browser send next? What if it had been 303?
With 307, a POST to /done with the same body: 307 forbids changing the method. With 303, a GET to /done, which is why Post/Redirect/Get uses 303.
Your client receives status 452, which no spec defines. How should it handle it?
As a 400: RFC 9110 says an unrecognized code is treated as the x00 code of its class. So: a client error, do not retry it unchanged.
Pick the code: a wrong password at login; a logged-in user opening an admin page; JSON with a required field missing; signing up with an email that is already registered.
401, 403, 422 (or 400 if your API uses one code for all bad input), and 409 Conflict.
A load balancer returns 504 after 60 seconds, but the app’s log shows the same request finished in 75 seconds. What happened, and is retrying that POST safe?
The proxy timed out at 60 s and gave up while the app kept working and completed the action. Retrying the POST may do it twice, so retry only with an idempotency key, or check state first.
Questions about HTTP Status Codes Cheat Sheet
What is the difference between 401 and 403?
401 Unauthorized really means unauthenticated: the request carried no credentials, or they were invalid or expired, so the server does not know who you are. It should include a WWW-Authenticate header saying how to authenticate, and logging in again may fix it. 403 Forbidden means the server knows who you are and you are still not allowed: your role or permissions do not cover this resource, and retrying with the same credentials will not help. Some APIs return 404 instead of 403 so that unauthorized callers cannot even learn that the resource exists.
What is the difference between 301, 302, 307 and 308 redirects?
301 and 308 are permanent: clients and search engines should update their links, and search engines move ranking signals to the new URL. 302 and 307 are temporary, so the original URL stays canonical. The second difference is the method. Historically, clients turned a POST into a GET when following 301 or 302, which the spec still permits, while 307 and 308 require the same method and body to be sent again. Use 301 or 308 for moved pages, 302 or 307 for temporary detours, and 303 to send a client to a results page after a form POST.
Should I use 400 or 422 for validation errors?
Use 400 Bad Request when the server cannot make sense of the request at all: malformed JSON, a wrong content type, or a missing required header. Use 422 Unprocessable Content when the request is well formed but its contents break your rules, such as an invalid email address, a negative quantity or an end date before the start date. Many APIs use 400 for both, which is acceptable if applied consistently. Either way, return a machine-readable body listing each failing field and the reason, for example in the RFC 9457 problem details format.
What is the difference between 502, 503 and 504?
All three usually come from a proxy, load balancer or gateway in front of your application. 502 Bad Gateway means the proxy reached the upstream server but got an invalid response or a dropped connection, often because the app crashed or is listening on the wrong port. 503 Service Unavailable means the service is deliberately not handling requests right now, because of overload, maintenance or no healthy instances, and it may include Retry-After. 504 Gateway Timeout means the upstream accepted the request but did not answer before the proxy’s timeout, which points to slow queries or calls.