HTTP Status Codes Reference & RFC 9110 Directory

The Semantic Architecture of HTTP Response Codes Under RFC 9110

In distributed computer networking, HyperText Transfer Protocol (HTTP) serves as the primary stateless application-layer communication protocol for the Internet. When an HTTP client issues a request to an origin server or intermediary proxy, the responder returns a numeric three-digit status code accompanied by a short textual reason phrase.

First codified under RFC 1945 (HTTP/1.0) and later expanded in RFC 2616 and RFC 7231, the canonical standard was consolidated in June 2022 under RFC 9110 ("HTTP Semantics") by the Internet Engineering Task Force (IETF). RFC 9110 defines status codes as three-digit integers where the initial digit establishes the semantic category of the response:

Critical Status Code Distinctions in Microservice Architectures

In distributed cloud environments involving reverse proxies (Envoy, Nginx, Cloudflare) and downstream Kubernetes pods, software engineers must distinguish between subtly differing failure codes:

1. 401 Unauthorized vs 403 Forbidden

A 401 Unauthorized explicitly indicates that authentication is missing or invalid. The response must include a WWW-Authenticate challenge header informing the client how to supply credentials. Conversely, a 403 Forbidden indicates that the server knows who the client is, but that authenticated user lacks the authorization permissions required to access the requested resource. Re-authenticating will not alter the outcome.

2. 502 Bad Gateway vs 503 Service Unavailable vs 504 Gateway Timeout

These three errors represent the most frequent production outage indicators:

• 502 Bad Gateway: The edge proxy successfully reached the upstream application server, but the upstream process crashed, closed the socket abruptly, or emitted an invalid HTTP framing header.
• 503 Service Unavailable: The server or upstream pool is temporarily unable to handle requests due to planned maintenance or severe CPU/connection pool saturation. It frequently includes a Retry-After header.
• 504 Gateway Timeout: The edge proxy established a connection to the upstream server, but the backend query took longer to process than the proxy's configured proxy_read_timeout (e.g. 60 seconds).

Core Status Code Reference Matrix

Best Practices for API Error Handling and Idempotency

When architecting RESTful services, engineering teams must maintain precise adherence to status code semantics:

• Never Return 200 OK with Embedded Errors: Anti-patterns where endpoints respond with 200 OK containing {"success": false, "error": "User not found"} break HTTP monitoring, CDN caching layers, and client-side retry mechanisms. Always emit appropriate 4xx or 5xx codes.
• Enforce Idempotency on 409 Conflict: When concurrent requests attempt to modify the same resource simultaneously (such as double booking an inventory item), return 409 Conflict with version headers (ETags) to allow optimistic concurrency control.