Vibe Engines
YouTube

Vibe Engines is free, interactive AI engineering & system design — runs in your browser. Pick a learning path

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.

1xx2xx3xx4xx5xxinterimsuccessredirectclient errorserver errorwait for finaluse the bodyfollow Locationfix the requestmaybe retry101 WebSocket201 + Location304 use cache408 429 retry502 503 504301 308 moved400 401 403 404500 = a bughighlight: retrydashed: do notnot an errorcaller's faultserver's fault
The first digit tells any client what to do next, even with a code it has never seen: RFC 9110 has clients treat an unknown code as the 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 Link headers 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 Range request 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 Allow header
410 Gone
deliberately removed for good — crawlers drop it faster than a 404
412 Precondition Failed
If-Match or If-Unmodified-Since did 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-Type is not one the endpoint accepts

4xx — Less common

406 Not Acceptable
nothing matches the client’s Accept headers
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
  1. 415, then 413. Both are the client’s problem and neither is worth retrying unchanged. A client that sends Expect: 100-continue learns about the 413 from the headers alone, before it uploads 3 GB.
  2. 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.
  3. 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.
  4. 206 and 304. A player seeks by asking for byte ranges; a revisit with the stored ETag costs headers only, not the video.
  5. 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 current

The 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 insists

This 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 twice

Jitter 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 Error

Returning 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 type and a readable detail.
  • 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

ChoiceGives youCosts
301 instead of 302clients and search engines update to the new URLbrowsers cache it, so a mistaken 301 keeps redirecting users after you remove it
404 instead of 403callers cannot probe which IDs existharder debugging for legitimate users with the wrong role
422 alongside 400clients can tell parse errors from rule errorsone more code to document and handle
200 with an error bodynothing in the path needs to understand HTTPmonitoring, 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-After tells 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.