The Devs Tools

Developer's Guide to HTTP Status Code Reference: Best Practices and Examples

August 18, 2026 · The Devs Tools Team

Every HTTP response begins with a three-digit status code that tells the client, in a single number, how to interpret what follows. The first digit defines the response's category: 1xx codes are informational and rarely surfaced to application code directly, 2xx codes indicate the request succeeded, 3xx codes signal that further action (usually following a redirect) is needed to complete the request, 4xx codes mean the client made a request the server won't fulfill as-is, and 5xx codes mean the server failed to fulfill an otherwise valid request. This structure lets HTTP clients, proxies, and caches make correct default decisions — retry, follow a redirect, surface an error — without parsing response bodies. In practice, though, status codes are one of the most inconsistently used parts of the HTTP spec: APIs routinely return 200 OK with an error payload in the body, conflate 401 and 403, or reach for 500 when a more specific 4xx code would tell the client exactly what to fix. Getting this right matters because status codes drive real behavior — browsers follow 301/302 automatically, HTTP clients retry 429 and 503 differently than 400, and monitoring tools alert on 5xx rates as a proxy for server health. A quick, accurate reference table is often faster than searching documentation mid-debugging session.

[!TIP] Need to double-check what a status code means right now? Try our free, local HTTP Status Code Reference to search and look up codes completely offline.

The Five Ranges at a Glance

  • 1xx — Informational: the request was received and processing continues. 101 Switching Protocols is the classic example, used when upgrading a connection to WebSockets.
  • 2xx — Success: the request was understood, accepted, and processed. 200 OK, 201 Created, and 204 No Content cover the vast majority of successful API responses, but they're not interchangeable — 201 implies a new resource now exists, while 204 implies success with an intentionally empty body.
  • 3xx — Redirection: the client must take additional action, typically fetching a different URL. 301 and 308 are permanent redirects; 302 and 307 are temporary ones, and the distinction affects whether clients update bookmarks or cache the redirect long-term.
  • 4xx — Client Error: the request itself is the problem. 400 Bad Request, 401 Unauthorized, 403 Forbidden, and 404 Not Found are the most common, but they mean different things — 401 means "we don't know who you are," 403 means "we know who you are and you're not allowed."
  • 5xx — Server Error: the server failed to process an otherwise valid request. 500 Internal Server Error is the generic catch-all; 503 Service Unavailable specifically implies a temporary condition, often paired with a Retry-After header.

Codes That Are Frequently Confused

401 Unauthorized  → Authentication is missing or invalid (misnomer: really means "unauthenticated")
403 Forbidden      → Authentication succeeded, but the action is not permitted
404 Not Found      → The resource doesn't exist, or the client isn't allowed to know it exists
409 Conflict       → The request conflicts with the current state (e.g. a version mismatch)
422 Unprocessable  → Syntactically valid but semantically invalid (validation errors)

Choosing 404 instead of 403 for a resource a user isn't authorized to see is a deliberate and common pattern — it avoids leaking the existence of protected data — while choosing 404 by accident when you meant 403 just makes debugging permission issues harder.

A Practical Workflow

  1. When an API call fails, check the exact status code before reading the response body — it usually points you to the right category of problem immediately.
  2. Reference which codes are safe to retry automatically (429, 502, 503, 504) versus which indicate a client-side bug that retrying won't fix (400, 404, 422).
  3. When designing your own API, pick the most specific applicable code rather than defaulting to 200 or 500 for everything — clients and monitoring tools depend on that specificity.

Conclusion

HTTP status codes compress a lot of meaning into three digits, but only when they're used precisely. Keeping the five-range structure and the commonly confused pairs straight turns status codes from decoration into a genuinely useful signal for both debugging and API design.