HTTP Status Code Lookup

Read the first digit before you read anything else

Every HTTP status code carries its diagnosis in the hundreds digit, and that single number decides who has to fix the problem. A 4xx means the request was wrong, so the browser, the mobile app or the curl command you typed owns the bug. A 5xx means the request was reasonable and the server failed to answer it, so the fix lives in application code, configuration or capacity. A 3xx means the resource lives somewhere else now, and a 2xx means it worked. That split saves hours: if you are staring at a 502 there is no point checking your JSON payload, and if you are staring at a 422 there is no point restarting the server.

The rule holds even for codes nobody documented. RFC 9110 requires clients to treat an unrecognised code as the generic x00 of its class, which is why a Cloudflare 521 can be reasoned about like a 500 and an nginx 499 like a 400 before you look anything up.

The five codes you will actually meet

404 Not Found is the friendliest failure on the list. The URL resolved, a server answered, and nothing lives at that path. Check capitalisation and the trailing slash first, because Linux servers are case sensitive and many routers treat /reports and /reports/ as different addresses. If the URL is correct, either the resource moved without a redirect or the route was never registered in the framework.

403 Forbidden means identity is not the problem, permission is. On shared hosting a 403 on a directory usually means there is no index.html and directory listing is switched off; in an application it means the logged-in user lacks a role. Sending the credentials again changes nothing, which is exactly what separates it from 401.

500 Internal Server Error is deliberately vague, because leaking a stack trace to the public is a security problem. The useful information is in the server log, and roughly nine times in ten it is an uncaught exception, a missing environment variable or a failed database connection that appeared right after a deployment.

503 Service Unavailable is a promise that the outage is temporary: overloaded workers, an exhausted connection pool, or a maintenance flag someone forgot to switch off. It is the only 5xx that is polite enough to be worth retrying automatically, especially when it arrives with a Retry-After header.

301 Moved Permanently is not an error at all, but it causes more lasting damage than any of the above when it is aimed at the wrong target. Browsers cache 301s hard, sometimes until the profile is cleared, so a redirect shipped to the wrong URL keeps sending returning visitors to the wrong place long after the server is fixed.

Worked example: a redirect chain that leaks ranking

Suppose an old page at http://example.com/old-guide is moved. Requesting it returns 301 to https://example.com/old-guide, which returns 301 to https://www.example.com/old-guide, which finally returns 302 to https://www.example.com/guides/new. That is three hops for every visitor and every crawler. The first two are the usual HTTP-to-HTTPS and non-www-to-www rules, and the last one is temporary, so the final destination never fully inherits the original page authority. Collapsing the chain to one 301 straight from the original URL to the final destination removes two round trips of latency and lets search engines consolidate the signals in one step. If the endpoint accepts POST, use 308 instead so the method survives the hop.

Retries, backoff and Retry-After

Only some failures are worth repeating. A 429 or a 503 usually includes a Retry-After header giving either a number of seconds or an HTTP date, and honouring it is the difference between a well-behaved client and one that gets blocked. A 408 or a 504 can be retried too, because the request may simply have been unlucky, but each retry should wait longer than the last: one second, then two, then four, with a small random jitter so that a thousand clients do not all return at the same instant. Codes such as 400, 401, 403, 404 and 422 will produce exactly the same answer no matter how many times you resend them, so retrying those only burns quota. For anything that is not idempotent, such as a POST that charges a card, add an idempotency key before you retry at all.

What a status code cannot tell you

The code describes the outcome of one HTTP exchange, not the health of the system. Plenty of APIs return 200 with an error object in the body, which hides failures from monitoring that only watches status codes. A CDN can return a cached 200 while the origin behind it is down, and a captive portal on hotel Wi-Fi can return 200 with a login page instead of the JSON you asked for. Treat the code as the first clue, then confirm with the response headers and body before concluding anything.