Featured Developer Sponsor • Zero-Token Protection
${sharedStyle}
RFC 9110 / RFC 9111
69 Status Codes
Zero-Dependency
HTTP Status Code Explorer & Header Architecture Studio
A precision diagnostic database and architectural reference for every standardized IETF HTTP status code, WebDAV extension, and edge proxy failure. Inspect caching semantics under RFC 9111, idempotency rules, mandatory HTTP headers, raw wire exchanges, and multi-language implementation patterns.
Showing 69 of 69 codes
Architectural Comparison Showdowns
Production DisambiguationSubtle semantic differences between related HTTP status codes create critical caching, routing, and security bugs. Select a comparison below to view the architectural breakdown:
| Property | 401 Unauthorized | 403 Forbidden |
|---|---|---|
| Core Semantic | Authentication failure: The client's identity is unverified, missing, or credentials (JWT, API key, Basic auth) expired. | Authorization failure: The identity is authenticated and known, but permissions/ACLs explicitly deny access. |
| RFC 9110 Requirement | MANDATORY WWW-Authenticate response header defining auth challenge scheme. |
No challenge header required. Body explains authorization deficiency. |
| Client Action | Authenticate, prompt login dialog, or refresh access token via OAuth2 flow. | Do NOT repeat request with same credentials. Request permission upgrade. |
| Browser Behavior | Triggers native browser credentials popup dialog if WWW-Authenticate: Basic. |
Displays page content directly without prompt. |
RFC 9111 HTTP Caching Semantics: Heuristic Freshness vs Explicit Validation
Under RFC 9111 Section 4.2.2, HTTP caches (CDNs, edge reverse proxies, browser caches) are permitted to calculate heuristic freshness for responses that omit explicit Cache-Control headers. If a response does not contain max-age or s-maxage, an intermediary may cache it if its status code is in the heuristic cacheable registry.
Heuristically Cacheable by Default (RFC 9111 §4.2.2):
200 OK • 203 Non-Authoritative Info • 204 No Content • 206 Partial Content • 300 Multiple Choices • 301 Moved Permanently • 404 Not Found • 405 Method Not Allowed • 410 Gone • 414 URI Too Long • 501 Not Implemented
CRITICAL PRODUCTION IMPLICATIONS:
• 404 Not Found Caching: Without
Cache-Control: no-cache, a transient 404 can be cached by Cloudflare/Fastly, serving errors long after the database record is created.• 301 Moved Permanently Poisoning: Browsers cache 301 responses indefinitely in local disk storage. If you point a 301 to the wrong URL, users cannot reach the site until their browser cache is manually cleared. Use 308 or temporary redirects during testing.
• 304 Not Modified: Validates conditional freshness via
If-None-Match (ETag) or If-Modified-Since. MUST NOT include a response body.5 Fatal Traps in HTTP Status Code Architecture
1. The 200 OK with { "error": true } Payload Anti-Pattern
Returning an HTTP
200 OK status code with a JSON payload containing { "success": false, "error": "Database down" } completely breaks the HTTP contract. Intermediaries, CDNs, API gateways, and APM tools (Datadog, New Relic) interpret 200 as a success, masking production failures from error rate alerts. Furthermore, public CDN caches may cache the failure response and serve it to thousands of legitimate users. Always use proper 4xx or 5xx status codes.
2. The 301/302 HTTP Verb Mutation and Body Dropping Trap
Browsers historically rewrite
POST requests to GET upon receiving a 301 Moved Permanently or 302 Found, silently dropping the request body. If you migrate API endpoints (e.g. from /v1/checkout to /v2/checkout) using 301 redirects, mobile apps and web clients will submit empty GET requests, corrupting order workflows. Always use 308 Permanent Redirect or 307 Temporary Redirect for API routes to enforce method and payload preservation.
3. Missing WWW-Authenticate Header on 401 Unauthorized
RFC 9110 Section 15.5.2 explicitly mandates: "The server generating a 401 response MUST send a WWW-Authenticate header field containing at least one challenge applicable to the target resource." Emitting a naked 401 without
WWW-Authenticate: Bearer realm="..." violates the RFC and breaks automated OAuth2/OIDC token refresh logic in client SDKs.
4. Default Negative Caching of 404 Not Found Responses
Because 404 is heuristically cacheable under RFC 9111, edge CDNs often cache 404 responses for 300 to 3600 seconds. If a user publishes a new blog post or creates a user account, and an automated webhook immediately requests the URL before database replication synchronizes across read replicas, the edge CDN caches the 404. All subsequent visitors will see a 404 error even though the record exists. Always attach
Cache-Control: no-cache, must-revalidate to dynamic entity routes.
5. Reverse Proxy Conflation of 502 Bad Gateway and 504 Gateway Timeout
Site Reliability Engineers frequently misdiagnose 504 Gateway Timeout errors as 502 Bad Gateway errors. A 502 indicates that the upstream service process is dead, crashing, or refusing TCP connections. A 504 indicates that the upstream service is alive, but stuck on a blocking database query, slow external API call, or thread pool exhaustion that exceeded
proxy_read_timeout. Blindly restarting servers on a 504 does not fix slow unindexed database queries.
200
OK
RFC 9110 §15.3.1
Heuristic Cacheable
Safe & Idempotent
Required & Recommended HTTP Headers
Raw HTTP Wire Protocol Exchange
Server Implementation Code
Frequently Asked Technical Questions
What is the precise architectural difference between 401 Unauthorized and 403 Forbidden?+
401 Unauthorized indicates an authentication failure (identity missing or invalid credentials) and under RFC 9110 Section 15.5.2 strictly requires a WWW-Authenticate challenge header. 403 Forbidden indicates an authorization failure where the client identity is authenticated and known, but their role, scopes, or ACLs lack permission to access or mutate the resource. Repeating the request with the same credentials will not change a 403 response.
Why does RFC 9110 recommend using 308 Permanent Redirect instead of 301 Moved Permanently for APIs?+
Historically, popular web browsers rewrote POST requests to GET when encountering 301 Moved Permanently or 302 Found, silently dropping the request body. RFC 9110 / RFC 7538 standardized 308 Permanent Redirect and 307 Temporary Redirect to strictly forbid user agents from changing the HTTP method or dropping the payload body, ensuring reliable REST API operations during route migrations.
Which HTTP status codes are heuristically cacheable under RFC 9111 without explicit Cache-Control headers?+
Under RFC 9111 Section 4.2.2, responses with status codes 200, 203, 204, 206, 300, 301, 404, 405, 410, 414, and 501 are heuristically cacheable unless an explicit Cache-Control directive (such as no-cache, no-store, or private) is present. In particular, 404 Not Found and 301 Moved Permanently can become cached by intermediate CDNs and proxies if Cache-Control headers are omitted.
How should asynchronous background operations return HTTP status codes in RESTful architectures?+
When an API accepts a request for long-running processing (e.g. video transcode, large report generation), it should return 202 Accepted with a Location header pointing to a task status polling URI (e.g. /tasks/123/status) and an optional Retry-After header indicating the recommended polling interval. Once completed, polling that URL returns 200 OK or 303 See Other pointing to the finalized resource.
What causes Cloudflare 520 through 525 errors compared to standard IETF 5xx gateway errors?+
Standard IETF 502 Bad Gateway and 504 Gateway Timeout indicate generic upstream process crashes or gateway socket read timeouts. Cloudflare 520–525 errors pinpoint specific edge-to-origin network failures: 521 means the origin refused the TCP connection on port 80/443; 522 means the TCP SYN handshake timed out (often a firewall dropping Cloudflare IPs); 523 means origin network routing or DNS failed; 524 means the origin accepted TCP but took longer than 100 seconds to send HTTP bytes; and 525 indicates TLS handshake or certificate negotiation failure.
Sponsored Utility
While You're Here
Sponsored Recommendations
Advertisement