fundamentals
HTTP Status Codes
Use the right status code so clients (and humans, caches, load balancers) know exactly what happened.
HTTP status codes are the standardised vocabulary an API uses to tell a client what happened, and using them correctly means clients, caches, load balancers, and monitoring tools can all react appropriately without parsing your response body. Returning 200 OK with an error message buried in the payload — a surprisingly common anti-pattern — defeats every piece of infrastructure that relies on the status line.
A traffic light. Green, yellow, red — universally understood. Inventing your own colors breaks every car on the road.
Key Concepts
1
The codes are organised by their leading digit. The 2xx range signals success: 200 OK for a successful read or update, 201 Created (ideally with a Location header pointing at the new resource) for a creation, 202 Accepted for work queued asynchronously, and 204 No Content for a success with nothing to return. The 3xx range handles redirection and caching, including 304 Not Modified for conditional requests. The 4xx range means the client erred and should not blindly retry the same request: 400 for malformed input, 401 for missing or invalid authentication, 403 for authenticated-but-forbidden, 404 for a missing resource, 409 for a conflict, 422 for semantic validation failures, and 429 for rate limiting. The 5xx range means the server failed — 500 for an unhandled error, 503 when temporarily unavailable — and these are the ones a well-behaved client may retry with backoff.
200 OK201 CreatedLocation202 Accepted204 No Content
2
The distinctions interviewers probe most are 401 versus 403 (not authenticated versus authenticated-but-not-allowed) and 400 versus 422 (syntactically bad versus syntactically valid but semantically rejected). The overarching principle is to let the status code carry the outcome and reserve the body for detail, so that the difference between "the client should fix their request" (4xx) and "the server had a problem, retry may help" (5xx) is unambiguous to everything in the request path.
401403400422