HTTP Status Codes

Everything that automates based on status codes breaks:

1. CDN caching — CDNs cache 200 responses. Your error response gets cached and served to other users.
2. Retry logic — HTTP client libraries and middleware retry on 5xx but not on 2xx. Your errors never trigger retries.
3. Monitoring/alerting — dashboards count 5xx rates. Your errors show as 0% error rate despite real failures.
4. Load balancer health checks — passive health checks count 5xx responses to detect failed backends. Your “200 with error” bypasses detection.
5. Browser behavior — 304 Not Modified saves bandwidth via conditional requests. If everything is 200, conditional caching doesn’t work.

HTTP status codes are a machine-readable API contract, not just a human convention.

301 (and 302) do not preserve the HTTP method. Per spec, browsers and many HTTP clients convert the redirected request from POST to GET. The client follows the redirect with GET /api/v2/orders instead of POST /api/v2/orders — no request body, no order created.

Fix: Use 308 Permanent Redirect (or 307 for temporary). Both preserve the original method and body. The client follows the redirect with POST /api/v2/orders and the order is created.

This is a real-world bug that has broken payment flows and form submissions. The 307/308 codes were specifically created to fix this ambiguity in 301/302.

502 Bad Gateway means the reverse proxy/load balancer received an invalid response from the backend, not that the backend is down. Possible causes:

1. Backend returned a malformed HTTP response — missing headers, truncated body, or non-HTTP response on an HTTP port
2. Connection reset by backend — backend accepted the connection but closed it before sending a response (crash during processing, timeout, or connection limit hit)
3. Protocol mismatch — the proxy expects HTTP/1.1 but the backend speaks HTTP/2 (or vice versa). Nginx’s proxy_pass doesn’t support HTTP/2 to backends — use grpc_pass for gRPC.
4. Backend timeout + proxy timeout misconfiguration — the backend timed out internally and sent a partial response that the proxy couldn’t parse

The backend appears “healthy” to local requests because the issue is in the proxy ↔ backend connection path, not the backend itself. Check proxy error logs, not just backend health checks.

Include Retry-After: N (seconds to wait) or Retry-After: <HTTP-date>. This tells the client exactly when it’s safe to retry.

The client should implement exponential backoff with jitter:

1. First retry: wait Retry-After seconds (or 1s if absent)
2. Subsequent retries: double the wait time (2s, 4s, 8s, …) up to a max (e.g., 60s)
3. Add random jitter (±20%) to prevent synchronized retry storms when many clients are rate-limited at the same time

Without jitter: If 1000 clients all get 429 at the same time and all retry after exactly 1 second, you get another spike of 1000 requests at t+1s. Jitter spreads retries across [0.8s, 1.2s], smoothing the retry wave.

Both approaches are valid — it depends on the threat model.

Returning 403: Confirms the resource exists but the user lacks permission. An attacker can enumerate resource IDs by distinguishing 403 (exists, no access) from 404 (doesn’t exist).

Returning 404: Hides the existence of resources the user can’t access. The attacker can’t distinguish “doesn’t exist” from “exists but forbidden.” This is called resource enumeration protection and is the approach GitHub, AWS, and most cloud APIs use for sensitive resources.

The auditor is wrong if the API intentionally uses 404 for security (documented behavior). The auditor is right if the API inconsistently returns 403 for some unauthorized resources and 404 for others — the inconsistency leaks information about which resources exist.