HTTP Status Codes Reference

HTTP Status Code Classes Explained

HTTP status codes are 3-digit numbers grouped by leading digit into five classes, each communicating a category of response:

• 1xx Informational (100 Continue, 101 Switching Protocols, 103 Early Hints): Provisional responses indicating the request is being processed. Rarely seen in app code; handled by HTTP libraries.
• 2xx Success (200 OK, 201 Created, 204 No Content, 206 Partial Content): Request was successfully received and processed. The default class for happy-path responses.
• 3xx Redirection (301, 302, 304, 307, 308): The client should take additional action — usually following a different URL. 304 Not Modified is special; it's a cache hit, not an error.
• 4xx Client Error (400, 401, 403, 404, 405, 409, 410, 422, 429): The client made a bad request. Auth issues, missing resources, conflict, invalid data, rate limits.
• 5xx Server Error (500, 502, 503, 504, 507): The server failed to fulfill a valid request. Bugs, dependency outages, capacity issues.

The 15 Most Common Status Codes in Practice

The 401 vs 403 Distinction (Frequent Mistake)

These two codes are constantly confused, but they have a specific meaning:

• 401 Unauthorized actually means "unauthenticated" — the request lacks valid credentials. Return this when no auth token is provided, when the token is invalid, or when the token is expired. Should always include a `WWW-Authenticate` header per RFC.
• 403 Forbidden means "authenticated but not allowed" — credentials are valid, but the user lacks permission for the specific resource. E.g., a logged-in regular user trying to access an admin endpoint.

Mnemonic: 401 = "who are you?" (need to authenticate); 403 = "I know who you are, but you can't do that."

400 vs 422 vs 409 for Validation Errors

All three are 4xx client errors, but they signal different validation failures:

• 400 Bad Request: the request was malformed at the HTTP / JSON level. Body isn't valid JSON, required header missing, wrong content-type. The server couldn't even parse the request.
• 422 Unprocessable Entity: the request parsed fine, but the data fails business logic validation. Email field doesn't match email format, age is negative, password is too short. This is what most REST APIs should return for "validation failed."
• 409 Conflict: the request was valid, but conflicts with current resource state. Duplicate email signup, stale ETag on PUT, trying to delete a resource with dependents.

Many APIs use 400 for everything client-side, but the more granular distinction helps client code respond appropriately (show form field errors for 422, show retry guidance for 429, show login dialog for 401, etc.).

5xx Debugging Decision Tree

• 500 Internal Server Error: check application logs first. Unhandled exception, NPE, type mismatch. Common: database connection lost, third-party API timeout caught wrong.
• 502 Bad Gateway: backend service is dead or returning garbage. Check if the upstream is up; check nginx/CloudFront logs; verify health checks pass.
• 503 Service Unavailable: capacity / overload / maintenance. Check resource exhaustion: CPU, memory, DB connections, request queue length.
• 504 Gateway Timeout: upstream took too long. Default timeouts: AWS ALB 60s, CloudFront 30s, nginx 60s. Check slow query logs.
• 507 Insufficient Storage: WebDAV / some object stores — disk full.

REST API Status Code Best Practices

• Use the correct verb-to-status mapping: GET success = 200, POST creating = 201, DELETE success = 204
• Always include structured error bodies: {"error":"code","message":"human readable","details":[...]} — even on 4xx/5xx
• Don't leak internals: never expose stack traces or DB error messages on 500 — use a correlation ID for log lookup instead
• Return 401 with `WWW-Authenticate` header: per RFC, this tells the client how to authenticate
• Return 429 with `Retry-After`: tell the client when to retry — in seconds or as an HTTP date
• Use 410 Gone (not 404) for deleted resources: signals to clients and search engines that the resource is permanently gone
• Use 200 + structured error vs 4xx for partial failures: e.g., a batch endpoint where 9/10 items succeeded — return 200 with per-item status array
• Cache appropriately: use `Cache-Control` + `ETag` so clients see 304 (not full 200) when content unchanged
• Use idempotency keys for unsafe operations: return the same response on retry, preventing duplicate side effects

Cloudflare-Specific 5xx Codes

Cloudflare adds custom 5xx codes when their edge can't reach your origin. Knowing them helps debug fast:

• 520: Origin returned empty or invalid response — usually origin webserver crashed
• 521: Origin web server is down (connection refused)
• 522: Connection timed out — origin took too long to respond
• 523: Origin is unreachable — DNS / firewall blocked Cloudflare
• 524: Origin responded but timed out (>100s) — long-running request
• 525: SSL handshake failed — wrong cert on origin
• 526: Invalid SSL certificate — cert chain broken
• 527: Railgun connection issue (rare)

Frontend Error Handling Pattern

On the client, use the status code class to drive UX behavior:

• 200-299: happy path — render success state
• 401: redirect to login or refresh token automatically
• 403: show "permission denied" — usually permanent UI state
• 404: show "not found" page or skeleton with friendly message
• 422: show field-level form errors using the structured error body
• 429: wait `Retry-After` seconds and retry once silently
• 5xx (except 503): log to Sentry, show toast "Something went wrong"
• 503: show maintenance notice if `Retry-After` is long, otherwise retry with backoff
• Network errors (no response): show "offline" state, retry on reconnection