HTTP Status Codes & REST API Design: Complete Error Handling Architecture

Master HTTP response status codes for scalable RESTful APIs. Detailed architectural patterns for 2xx success, 3xx redirects, 4xx client errors, and 5xx server failures.

1. Categorical Structure of HTTP Responses (RFC 9110)

The Hypertext Transfer Protocol defines standardized 3-digit numeric status codes grouped into 5 categorical ranges: 1xx (Informational), 2xx (Successful), 3xx (Redirection), 4xx (Client Error), and 5xx (Server Error). Accurate status codes allow API clients, reverse proxies, and browsers to make deterministic caching and retry decisions. Explore all definitions in the HTTP Status Codes Reference.

2. Disambiguating 401 Unauthorized vs. 403 Forbidden

A frequent design flaw in REST APIs is conflating authentication with authorization: • 401 Unauthorized: The request lacks valid authentication credentials. The client may retry after supplying a valid Bearer token, session cookie, or API key in the `Authorization` header. • 403 Forbidden: The client is successfully authenticated, but lacks sufficient permissions or roles (e.g., standard user attempting to access admin endpoints). Retrying with the same credentials will fail.

3. Handling Updates and Conflicts: 409 Conflict vs. 412 Precondition Failed

When multiple clients modify identical resources concurrently, status codes provide essential concurrency guarantees: • 409 Conflict: Signals state collision, such as attempting to register an email that already exists or committing an edit with an out-of-sync revision ID. • 412 Precondition Failed: Used with conditional HTTP headers (`If-Match: "etag"`). If the server entity tag has changed, the server rejects the write without executing changes, preventing lost updates.

4. Transient vs. Permanent Errors: 429 Rate Limiting, 502, and 504

Edge proxies and API gateways communicate upstream failures using specific codes: • 429 Too Many Requests: Client has exceeded rate limits. Should be accompanied by a `Retry-After: 60` header. • 502 Bad Gateway: The reverse proxy received an invalid or terminated response from the upstream microservice. • 504 Gateway Timeout: The upstream server failed to complete processing within the gateway timeout window. Inspect network request waterfalls and gateway error headers visually using the HAR File Viewer.

5. Standardized Error Response Bodies with RFC 7807 (Problem Details)

Modern APIs should standardize error payload JSON schemas using RFC 7807 Problem Details to ensure machine-readable diagnostic feedback:

RFC 7807 compliant error payload structure

{
  "type": "https://api.outlivo.tech/errors/invalid-parameter",
  "title": "Invalid Request Parameters",
  "status": 422,
  "detail": "The 'loanTermYears' field must be an integer between 1 and 40.",
  "instance": "/api/v1/calculators/loan/req-98214"
}

Key Takeaways

Use 401 for unauthenticated requests and 403 for authenticated requests with insufficient privileges.
Always return a Retry-After header with 429 Too Many Requests responses.
Never return 200 OK with an error payload inside the JSON body.
Adopt RFC 7807 Problem Details for consistent, structured API error messaging.

Written by Pradhumn PawarAuthor & Site Operator

Founder and engineer at Outlivo. Building privacy-first, client-side web tools, developer utilities, and technical guides. Published on 2026-08-26.

Back to all guides

Launch HTTP Status Codes Reference