Reading — step 1 of 5
Read
~1 min readProduction Features
Errors & Status Code Semantics
Every error condition maps to a specific status code. Picking the wrong one breaks client behavior:
| Code | When |
|---|---|
| 400 | Malformed request the client should fix |
| 401 | Authentication required (with WWW-Authenticate header) |
| 403 | Authenticated but not authorized |
| 404 | Resource doesn't exist |
| 405 | Method not allowed for this URL (must include Allow header) |
| 408 | Client took too long sending the request |
| 409 | Conflict (e.g., editing stale data) |
| 413 | Body too large |
| 414 | URI too long |
| 415 | Unsupported Media Type (Content-Type your server can't parse) |
| 429 | Too many requests (rate-limited) |
| 500 | Generic server error (programmer's fault) |
| 502 | Bad gateway (upstream server returned garbage) |
| 503 | Service unavailable (overload, maintenance) |
| 504 | Gateway timeout (upstream too slow) |
Never use 500 as a default for client mistakes — it tells your client team "this is your problem to debug" instead of "I sent bad data."
Always include a body (even a brief plaintext explanation). Browsers, curl users, and ops engineers all read it.
Discussion
Ask a question, share an insight, or help someone who’s stuck.
Sign in to post a comment or reply.
Loading…