HTTP Status Code Directory & Header Inspector
Search and inspect all standard IETF RFC 9110 HTTP status codes, Cloudflare 52x edge errors, and reverse proxy codes with root cause explanations and diagnostic cURL commands.
The Architecture of HTTP Semantics: RFC 9110 Specification
Hypertext Transfer Protocol (HTTP) status codes represent the universal signaling protocol governing client-server communication across the World Wide Web. Standardized under the Internet Engineering Task Force (IETF) specification RFC 9110 (HTTP Semantics), every status code is a 3-digit integer where the first digit identifies the general response category:
| Status Range | Formal Class Category | Syntactic Architectural Purpose | Typical Browser & Cache Behavior |
|---|---|---|---|
| 1xx | Informational | Request received, continuing process (e.g., 101 Switching Protocols) |
Interim response; non-cacheable |
| 2xx | Success | Action successfully received, understood, and accepted | Normal payload consumption; cacheable if headers allow |
| 3xx | Redirection | Further action needed to complete request (URL relocation) | Client follows Location header; 301 is cached indefinitely |
| 4xx | Client Error | Request contains bad syntax or cannot be fulfilled by client fault | Client must rectify request parameters; safe to cache error pages |
| 5xx | Server Error | Server failed to fulfill an apparently valid incoming request | Upstream origin failure; triggers circuit-breakers and retry queues |
Triage Runbook: 502 Bad Gateway vs 504 Gateway Timeout
In Kubernetes microservices and reverse proxy architectures (NGINX, Traefik, HAProxy, AWS ALB), two errors generate the vast majority of P1 on-call incidents:
| Diagnostic Dimension | 502 Bad Gateway | 504 Gateway Timeout |
|---|---|---|
| Underlying Cause | Upstream service rejected connection or crashed | Upstream service took too long to respond |
| TCP Socket State | TCP RST packet received or immediate socket drop |
TCP connection established, but read buffer timed out |
| Typical Culprit | Node process died (OOM killer), Pod rebooting, Port misconfiguration | Slow database query, external API hanging, connection pool exhaustion |
| NGINX Timeout Setting | proxy_connect_timeout (Connection refused) |
proxy_read_timeout (Exceeded 60s default) |
Cloudflare 52x Edge Error Troubleshooting Guide
When routing traffic through Cloudflare’s global edge network, proprietary 52x HTTP error codes pinpoint breakdowns between the Cloudflare Edge and your origin server:
- 520 Web Server Returned an Unknown Error: Origin sent an empty response, dropped the TCP connection abruptly, or returned response headers exceeding 32KB.
- 521 Web Server Is Down: Cloudflare edge attempted a TCP handshake with your origin IP on port 80/443, but the origin server actively refused the connection (NGINX/Apache daemon is stopped or firewall is dropping packets).
- 522 Connection Timed Out: Cloudflare TCP SYN packet received no SYN-ACK from origin within 15 seconds. Almost always caused by hosting provider routing rate limits or iptables blocking Cloudflare IP ranges.
- 524 A Timeout Occurred: TCP handshake succeeded and HTTP request was sent, but origin failed to send HTTP response headers within 100 seconds (long-running batch query timeout).
HTTP Caching Semantics: RFC 9111 & Conditional Validation
Efficient API and CDN edge architectures rely on the precise interplay between HTTP status codes and caching headers standardized in RFC 9111 (HTTP Caching):
| Status Code | Primary Caching Header | Cache State Mechanism | Bandwidth & Egress Optimization |
|---|---|---|---|
200 OK |
Cache-Control: public, max-age=3600, stale-while-revalidate=86400 |
Fresh in CDN edge cache for 1 hour; serves stale while revalidating in background | Cuts origin database load by 98% |
304 Not Modified |
ETag: "hash-3a8f" / If-None-Match |
Zero Payload Body: Validates that client’s cached copy is byte-for-byte identical | Saves 99.5% bandwidth; sends only ~200 bytes of response headers |
404 / 410 |
Cache-Control: public, max-age=300 |
Negative caching: caches the absence of resource to protect origin from 404 flooding | Prevents Denial of Service from scrapers crawling dead links |
500 / 502 / 503 |
Cache-Control: no-store, no-cache, must-revalidate |
Strictly Non-Cacheable: Prevents CDNs from caching transient server crashes | Guarantees users see restored service immediately post-recovery |
The Microservices Circuit Breaker Pattern
In distributed microservice topologies, a single downstream dependency returning 500 Internal Server Error or 504 Gateway Timeout can trigger cascading cluster failure. If 500 concurrent requests hang waiting for a slow payment database, application thread pools become exhausted, collapsing the entire API gateway.
Circuit Breaker State Machine (Resilience4j / Envoy)
1. CLOSED State (Normal Operation): - All requests pass through to downstream service. - Failure rate tracked (e.g., % of 5xx responses over 100 requests). 2. OPEN State (Tripped / Broken): - When 5xx failure rate exceeds threshold (e.g., > 50%), circuit TRIPS to OPEN. - ALL incoming requests are IMMEDIATELY failed with 503 Service Unavailable or fallback response. - Zero traffic hits the struggling downstream service, allowing it to recover. 3. HALF-OPEN State (Testing Recovery): - After a cooldown period (e.g., 30s), circuit enters HALF-OPEN. - A limited sample of trial requests (e.g., 5 requests) is permitted through. - If successful, circuit resets to CLOSED; if failures persist, resets to OPEN.
HTTP Method Idempotency & Safety Matrix
A frequent root cause of financial double-billing and data corruption is misunderstanding HTTP method semantics:
- Safe Methods (
GET,HEAD,OPTIONS): Pure read-only requests that do not alter server state. Browsers and proxies can safely retry these automatically. - Idempotent Methods (
PUT,DELETE): Executing the request \(N\) times produces the exact same final server state as executing it once. Retrying a failedPUTis safe. - Non-Idempotent Methods (
POST,PATCH): Each execution creates a new resource or triggers an action. Never retry a failed POST request without anIdempotency-KeyHTTP header! In payment gateways like Stripe, passingIdempotency-Key: uuid-v4guarantees that network timeouts will never double-charge a customer.
RFC 7807: Problem Details for Standardized API Error Payloads
A persistent anti-pattern in REST API design is returning custom, non-standardized error JSON structures (e.g., {"err": "failed"} vs {"error_code": 104}). The IETF standardized error communication via RFC 7807 (Problem Details for HTTP APIs) using the application/problem+json media type:
RFC 7807 Standard Error Response (HTTP 403 Forbidden)
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en
{
"type": "https://api.zelobiz.com/errors/insufficient-permissions",
"title": "Forbidden: Insufficient RBAC Permissions",
"status": 403,
"detail": "Account ID 4920 does not possess the 'billing:admin' role required to modify invoice schedules.",
"instance": "/invoices/inv_98234/cancel"
}
WebSocket Upgrades: The 101 Switching Protocols Handshake
To establish full-duplex, low-latency persistent communication (such as real-time financial order books, chat systems, or multiplayer games), web clients initiate an HTTP request that upgrades into a WebSocket (RFC 6455):
- The Client Request:
GET /chat HTTP/1.1withUpgrade: websocket,Connection: Upgrade, and a cryptographicSec-WebSocket-Key. - The Server Response:
101 Switching ProtocolswithSec-WebSocket-Accept(calculated asSHA1(Key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11")in Base64). - The Result: The underlying TCP socket remains open, transitioning from HTTP request/response semantics into lightweight bidirectional binary/text framing.
HTTP/2 & HTTP/3 Graceful Server Draining: GOAWAY Frames
During zero-downtime rolling deployments, shutting down a backend server that handles multiplexed HTTP/2 or HTTP/3 streams without dropping active client requests requires GOAWAY frame signaling:
- The server emits a
GOAWAYframe indicating the highest stream ID it has processed, instructing the client to cease opening new streams on this connection while finishing all active in-flight streams. - Load balancers (like AWS ALB or NGINX) wait for the deregistration delay (connection draining timeout, e.g., 30s) before terminating the process, eliminating
502 Bad Gatewayspikes during deployments.
Early Hints: Leveraging HTTP 103 for Sub-Second Web Performance
One of the most powerful advancements in HTTP performance engineering is HTTP 103 Early Hints (RFC 8297). In traditional web architectures, the browser sends a request, the server takes 200ms to query the database and render HTML, and only then does the browser discover which CSS stylesheets and font files to download.
- The 103 Workflow: The instant the edge server receives the HTTP request, it immediately fires an interim
103 Early Hintsresponse withLink: </app.css>; rel=preload; as=styleheaders. - Concurrent Fetching: While the origin server is busy calculating the database query, the browser starts downloading critical CSS and web fonts in parallel, slashing Largest Contentful Paint (LCP) by up to 30%.
Terminal Mastery: Inspecting HTTP Latency & Headers via cURL
High-Precision cURL Latency Profiler
# Save formatting template:
cat << 'EOF' > curl-format.txt
DNS Lookup Time: %{time_namelookup}s\n
TCP Handshake: %{time_connect}s\n
TLS Negotiation: %{time_appconnect}s\n
Time to First Byte: %{time_starttransfer}s\n
Total Response: %{time_total}s\n
EOF
# Profile any HTTP endpoint:
curl -w "@curl-format.txt" -o /dev/null -s https://zelobiz.com
Frequently Asked Questions About HTTP Status Codes (PAA)
301 Moved Permanently passes approximately 95-99% of PageRank link equity to the destination URL and tells search engines to update their canonical index. A 302 Found (Temporary Redirect) instructs search engines that the move is temporary, preserving the original URL in search results and passing minimal link equity.401 Unauthorized strictly means “Unauthenticated”—the client has not provided valid credentials (such as an Authorization Bearer token). 403 Forbidden means the client is authenticated, but lacks sufficient permissions (RBAC) to access the requested resource. Re-authenticating will not alter a 403 response.429 Too Many Requests indicates that the client has exceeded rate limits within a given time window (e.g., token bucket exhaustion). RFC 6585 dictates that servers should include a Retry-After header specifying the exact seconds the client must wait before retrying.418 I'm a Teapot was formally preserved by IETF in RFC 9110 as a reserved status code acknowledging historical implementation across thousands of web servers and client libraries.