Status codes are an API contract
Clients retry, cache, and surface errors based on status codes. Returning 200 with an error body, or 500 for a missing resource, quietly breaks that contract and makes monitoring harder.
The mix-ups
Memorize these distinctions:
- 401 Unauthorized — authentication is missing or invalid; client should log in
- 403 Forbidden — authenticated, but not allowed for this resource
- 404 Not Found vs 410 Gone — unknown vs deliberately removed
- 502 Bad Gateway vs 504 Gateway Timeout — upstream error vs upstream too slow
- 429 Too Many Requests — include Retry-After when you can
Look them up fast
The HTTP Status Explorer on code.live is a searchable reference for every common code and what it means — useful when you're writing OpenAPI docs or debugging a weird gateway response.