Why Status Codes Are Your First Diagnostic Signal
Every HTTP response carries a three-digit status code, and that single number is often the fastest diagnostic signal you have. Before you open a log file or a tracing dashboard, the status code already tells you whether the request succeeded, was redirected, was rejected because of something the client did, or failed because of something on your server. Reading status codes correctly — and monitoring them systematically — is one of the cheapest, highest-leverage habits in API observability.
The problem is that most teams treat status codes as binary: "200 is good, anything else is bad." That mental model misses critical distinctions. A 404 on a typo'd URL is normal internet noise; a 404 on an endpoint that worked yesterday is a regression. A 401 spike right after a token rotation is expected; the same spike at 3 AM with no deploy is an incident. This guide breaks down every status code range so your monitoring can tell these situations apart.
2xx Success: What "Working" Actually Means
200 OK is the default success response, but it is not the only one worth distinguishing. 201 Created confirms a resource was actually persisted — if your API returns 200 instead of 201 after a POST, it is a signal that your response semantics have drifted from the convention your clients expect. 204 No Content is correct for successful requests with nothing to return, such as a DELETE; returning a 200 with an empty body instead is a common but harmless inconsistency worth standardizing.
The trap with 2xx codes is assuming they prove correctness. A 200 OK with a malformed or empty JSON body is still a 2xx in every dashboard, which is exactly why status-code monitoring alone is not enough — pairing it with content assertions catches the failures a status code alone will never reveal.
3xx Redirects: When Success Isn't the Full Story
Redirects are rare in JSON APIs but common on web-facing endpoints, and they deserve more attention than they usually get. 301 Moved Permanently and 308 Permanent Redirect tell clients and search engines to update their stored URL; if a monitor keeps hitting a 301 forever without ever reaching a final 200, something in the redirect chain is broken or looping. 302 Found and 307 Temporary Redirect should resolve to a 2xx on the next hop — a monitor that does not follow redirects will falsely report an outage for a perfectly healthy endpoint.
304 Not Modified is a special case worth tracking separately: it confirms your caching layer (ETags, conditional GET) is working. A sudden drop in 304 responses, replaced by full 200 payloads, usually means a caching header regressed in a recent deploy — a performance problem long before it becomes an outage.
4xx Client Errors: Whose Fault Is It, Really?
4xx codes are labeled "client errors," but that label is misleading for monitoring purposes — a sudden 4xx spike is very often your fault. 400 Bad Request spiking right after a deploy usually means a validation rule changed and existing clients are now failing to comply with it. 401 Unauthorized and 403 Forbidden are expected in isolation (bad credentials, expired tokens), but a sudden site-wide spike points to a broken auth service or a misconfigured gateway, not to thousands of users suddenly mistyping their passwords.
404 Not Found deserves a baseline rather than a hard alert — the internet is full of scanners and stale links. What matters is the delta: if a specific endpoint that used to return 200 starts returning 404, that is a routing regression, not background noise. 429 Too Many Requests is the one 4xx you should almost always alert on for critical integrations — it means legitimate traffic is being throttled, and if it persists it degrades exactly the users you care most about.
5xx Server Errors: The Codes That Should Wake You Up
5xx codes are unambiguous: something on your side of the wire failed. 500 Internal Server Error is the generic catch-all — useful as a smoke alarm, but you should always dig into logs to find the real exception behind it. 502 Bad Gateway means your load balancer or reverse proxy could not get a valid response from an upstream service — check the health of what sits behind your gateway, not the gateway itself. 503 Service Unavailable usually indicates the service is intentionally refusing traffic (overload protection, maintenance mode, or a tripped circuit breaker), while 504 Gateway Timeout means the upstream took too long to respond at all.
These three — 502, 503, 504 — are frequently confused but point to different layers of your stack, and alerting on "5xx" as one bucket wastes the diagnostic value the specific code already gives you for free. A monitoring setup that surfaces the exact code, not just "5xx detected," cuts triage time from minutes to seconds.
