HTTPLens
Interactive Architecture Tool

HTTP Status Code Decision Picker

Follow the guided RFC 9110 decision path or search by scenario to identify the correct HTTP status code, understand mandatory headers, and avoid common API anti-patterns.

Zero-Log Diagnostic: Runs entirely in your browser runtime. Nothing leaves this page.
1. Problem Domain2. Specific Scenario3. Specification Recommendation

What type of API situation or failure are you handling?

Select the problem domain that matches your client or server state:

Core Principles of HTTP Status Code Selection

Selecting the correct HTTP status code is essential for predictable API contracts, client SDK retry logic, and CDN caching behavior. According to RFC 9110, status codes are organized into five fundamental semantic classes:

1. Client Error (4xx) vs Server Error (5xx)

4xx codes signal that the fault originates with the client (bad syntax, missing authorization, nonexistent resource). Retrying without modifying the request will consistently produce the same error.

5xx codes signal that the origin server or intermediate proxy failed to process a syntactically valid request. Retrying may succeed once the server recovers.

2. Authentication (401) vs Authorization (403)

401 Unauthorized means unauthenticated (missing or invalid credentials) and MUST include a WWW-Authenticate challenge header.

403 Forbidden means unauthorized (identity is established, but the client lacks permission or scope). Re-authenticating with the same identity will not help.

3. Syntax (400) vs Semantic Validation (422)

400 Bad Request is strictly for malformed JSON, corrupted message framing, or illegal characters that prevent parsing.

422 Unprocessable Content is the standard status when JSON parses successfully, but schema validation rules (missing required keys, invalid email formats) fail.

4. Timeouts: Client (408) vs Gateway (504)

408 Request Timeout is triggered by the origin server when the client takes too long to send data over the TCP socket.

504 Gateway Timeout is emitted by a reverse proxy or load balancer (e.g. NGINX, Cloudflare) when the upstream application backend fails to respond within the gateway timeout threshold.

Frequently Asked Questions

Should I return HTTP 200 with an error object inside?

No. Returning 200 OK with { "error": true } in the response payload is an API anti-pattern. It breaks HTTP caching layers, prevents automated client retry handlers from recognizing failures, and pollutes monitoring dashboards with false positive success rates.

When should I use 404 vs 403 to hide sensitive resources?

If disclosing that a resource exists poses a security or privacy risk (e.g. /admin/financial-reports/user-123), RFC 9110 permits servers to return 404 Not Found instead of 403 Forbidden to prevent resource enumeration attacks.

Which headers are legally required with error status codes?

Certain HTTP status codes have mandatory RFC headers:

  • 401 Unauthorized: Must include WWW-Authenticate.
  • 405 Method Not Allowed: Must include Allow listing supported verbs.
  • 407 Proxy Auth Required: Must include Proxy-Authenticate.
  • 429 / 503: Strongly recommended to include Retry-After.