Chapter 4 — HTTP Status Codes, and Who Sent Them

A Status Code Is a Claim — First Find Out Who Is Making It

Part 1: Foundations. Prerequisites: Chapters 1–3.

---

Opening

Every HTTP response starts with a three-digit status code. Most engineers know the famous ones — 200, 404, 500 — and treat the rest as noise. That loses most of the evidence.

A status code is a precise claim about what happened to a request. And here is the part almost everyone misses: it is a claim made by whoever produced the response — which is often not your application. Between the browser and your code sit a CDN, a load balancer, a reverse proxy, maybe an API gateway. Any of them can answer the request themselves. A 502 from your load balancer, a 403 from a CDN's firewall and a 403 from your own permission check look identical in a quick glance and mean completely different things.

This chapter gives you two skills. First, what each status code actually claims. Second — and more important — how to work out which hop sent it, because that decides where you look next.

---

Part 1: The Chain a Request Travels Through

A request from a browser to your API usually passes through several systems. Each one can either forward the request onward or answer it directly.

The words for these roles:

• Client — whoever sends the request (the browser, a mobile app, another service).
• Origin — your actual server, the thing the CDN or proxy forwards to.
• Proxy / reverse proxy — a server that receives requests on behalf of others and forwards them. nginx and load balancers are reverse proxies.
• Gateway — a proxy acting as the entry point to backend services. In status-code language, any proxy forwarding to an upstream is "the gateway" — which is why 502 and 504 are called Bad Gateway and Gateway Timeout.
• Upstream — the next system toward the origin, from a given hop's point of view. To the load balancer, your app is upstream. To your app, the database is upstream.
• Downstream — the direction back toward the client.

So 502 Bad Gateway means: "I am a proxy, and the upstream I forwarded to gave me a bad response or none." It is generated by the proxy. Your app may never have seen the request, or may have crashed handling it.

---

Part 2: Who Sent This Response?

Before interpreting any error status, answer this question. Four kinds of evidence settle it.

1. Response headers. Each layer tends to stamp its own:

2. The body. Your API returns errors in its own JSON shape, like { "error": { "code": "ORDER_NOT_FOUND" } }. A plain HTML page that says "502 Bad Gateway — nginx" or a branded CDN error page was not written by your code.

3. Timing. How long did the request take? A 504 that arrives after exactly 30.0 or 60.0 seconds is almost certainly a proxy's configured timeout, not something your code decided. An error that arrives in 3 milliseconds probably never reached a slow backend.

4. Your app's logs. Search for the request (by time, path, or request ID). If your app has no record of it, the response came from a layer in front of your app — and debugging your app's code is pointless until you know why the request never reached it.

---

Part 3: The Five Classes

The first digit is the class. It tells you whose fault it is likely to be and whether retrying makes sense.

The 4xx/5xx split is the most useful part. A 4xx says "this exact request will keep failing until something about it changes." A 5xx says "this request may be fine; something on the server side broke."

---

Part 4: 1xx, 2xx and 3xx — the Ones That Still Cause Bugs

1xx — rarely seen, occasionally important

• 101 Switching Protocols — the server agreed to upgrade the connection, most often to a WebSocket. If a WebSocket fails to connect, check whether you got 101; a proxy that does not support upgrades returns something else.
• 103 Early Hints — the server sends hints (like "start loading this CSS") before the real response is ready.

2xx — success, with traps

3xx — redirects and caching

Three redirect bugs worth knowing:

1. A wrong 301 sticks. Browsers cache permanent redirects, so even after you fix the server, users who saw the bad 301 keep being redirected until their cache clears. Use 302/307 while you are unsure.
2. A POST redirected with 301/302 can arrive as a GET with no body. If a form submission "loses its data", check for a redirect — commonly http→https or a missing/extra trailing slash — and use 307/308 or fix the URL.
3. fetch follows redirects silently. You get the final response, not the redirect. Check response.redirected and response.url. A response that "should be JSON" but is the login page HTML is usually a silent redirect to /login (Chapter 2).

304 and the browser cache. A conditional request asks "has this changed since my copy?" using If-None-Match (with an ETag) or If-Modified-Since. 304 means "no, use your copy." In DevTools, also watch for 200 (memory cache) or 200 (disk cache) — those were served from the browser's cache without any request at all. If a change "isn't showing up", check whether the response came from cache.

---

Part 5: 4xx — The Request Is the Problem

401 versus 403 — the pair everyone mixes up

The 404 that only happens on refresh

A single-page app works when you click around, but refreshing /dashboard/settings gives 404. The browser asked the server for /dashboard/settings as a real file, and a static host has no such file — the route only exists inside the JavaScript router. The host must be configured to serve index.html for unknown paths.

---

Part 6: 5xx — Something on the Server Side Failed

502 versus 504 — fast failure or slow failure

• 502 usually arrives quickly. The proxy tried the upstream and got a refused or broken connection. Look at whether the app is running and healthy: crashes, restarts, deploys, ECONNRESET, keep-alive mismatches (Chapter 3).
• 504 arrives after the proxy's timeout. The upstream accepted the request and did not answer in time. Look at why the app is slow: a slow query, a lock, a hung call to a third-party API, an exhausted connection pool.

The dangerous thing about 504

A 504 means the proxy stopped waiting. It does not mean your app stopped working. The app may still be processing — and may finish successfully after the client has already been told it failed.

Idempotency keys are covered in depth in SD QA Q26.

Platform and CDN codes

CDNs and platforms add their own codes and labels. Learn the ones for whatever you deploy on.

• Vercel names platform errors in the x-vercel-error header and the error page — for example FUNCTION_INVOCATION_TIMEOUT (504: your function exceeded its time limit), FUNCTION_INVOCATION_FAILED (500: your function crashed), FUNCTION_PAYLOAD_TOO_LARGE (413).
• Cloudflare uses the non-standard 52x range between Cloudflare and your origin: 520 (the origin returned something unexpected), 521 (the origin refused the connection — it is down), 522 (connecting to the origin timed out), 524 (connected, but the origin took too long to respond), 525/526 (TLS problems with the origin).

A 52x tells you immediately: Cloudflare is fine; the hop from Cloudflare to your origin failed.

---

Part 7: Things That Look Like Status Codes but Are Not

Some of the most confusing "errors" in the Network tab are not HTTP statuses at all.

CORS hides the real error. If an API returns 500 without CORS headers, the browser reports a CORS error, not the 500. Before "fixing CORS", check the request in the Network tab and in the server logs — the CORS error may be a symptom of a crash on the server.

---

Part 8: The Status-Code Reflex

---

The Causal Chains

---

The Rule You Keep Forever

A status code is a claim, and the first question is always who made it. Check the headers, the body, the timing and your own logs before deciding the code is about your app — and treat every 504 as "I stopped waiting", never as "nothing happened."

---

Vocabulary Map

---

Practice Problems

Problem 1 — Who sent it? A user reports a 403. The response body is an HTML page with your CDN's branding, and your app's logs have no record of the request. What does this tell you, and what are the next two things you check?

Problem 2 — Fast or slow. Two incidents: in the first, users get 502 within 50 ms; in the second, users get 504 after exactly 60 seconds. For each, give your two leading hypotheses and the first place you look.

Problem 3 — The disappearing body. A signup form works locally. In production, the server receives the request as GET /signup/ with no body. The form posts to /signup. What is happening, and how do you confirm it?

Problem 4 — CORS or crash? The browser shows a CORS error on POST /api/orders, but only for orders with more than 50 items. Smaller orders work. Why is "add the CORS header" probably the wrong first move, and what do you check instead?

Problem 5 — The 504 retry. Your mobile app automatically retries any request that fails with 504. Which endpoints does this make dangerous, and what two changes make the retry safe?

---

What's Coming Next

Part 1 gave you the language: the method, the errors, the codes, the statuses. Part 2 gives you the instruments. Chapter 5 opens the most-used one — the browser's DevTools — and goes through it the way a senior engineer uses it during an investigation: the Network panel's waterfall and timing breakdown, the request initiator, breakpoints that pause only when something interesting happens, and the Application panel where cookies, storage and service workers quietly cause bugs.