API design
HTTP status code design: interview questions and practical design
HTTP status code design maps an operation’s outcome to a stable protocol signal that clients, operators, and intermediaries can act on.
Written and reviewed by Sahil Srivastav
What it actually is
HTTP status code design maps an operation’s outcome to a stable protocol signal that clients, operators, and intermediaries can act on.
If validation, conflict, outage, and success all return 200, clients cannot choose safe retry or correction behaviour.
The useful interview answer is precise about the boundary: Use 2xx for accepted success, 4xx for a caller or resource-state problem, and 5xx when the server cannot fulfil a valid request. Do not encode a validation error as a server outage.
Why it matters in production
If validation, conflict, outage, and success all return 200, clients cannot choose safe retry or correction behaviour.
The code is only useful when paired with a consistent error body, request identifier, and documented retry meaning.
How it works
Outcome categories
Use 2xx for accepted success, 4xx for a caller or resource-state problem, and 5xx when the server cannot fulfil a valid request. Do not encode a validation error as a server outage.
Conflict and preconditions
409 describes a state conflict such as a duplicate or version race; 412 reports a failed conditional request. The distinction helps clients decide whether to refresh, merge, or change input.
Retry semantics
A 429 or transient 503 may be retryable with a deadline; a 400 or 422 generally needs correction. Make that policy explicit rather than relying on status alone.
Implementing it
Write an error matrix for validation, unauthorised access, missing resource, conflict, throttling, and dependency failure.
Return one structured error shape with a stable code and correlation id.
Test that clients do not retry permanent 4xx responses.
Interview questions and how to answer them
400 or 422 for validation?
Pick a documented convention. 400 is broadly understood for malformed requests; 422 can distinguish a well-formed request that violates domain validation. Consistency matters more than a universal choice.
When is 409 appropriate?
When the request is valid but conflicts with current resource state, such as a uniqueness collision or optimistic version mismatch.
What should an error body contain?
A stable machine-readable code, safe human detail, field errors when useful, and a request id. Never require clients to parse prose.
Answers that lose the round
- Returning 200 with `{error: ...}` for every failure.
- Using 404 to hide an authorisation decision without considering information leakage.
- Returning 500 for malformed client input.
- Using 202 when the server has not actually accepted or tracked the work.
FAQ
Should 500 expose the exception?
No. Return a safe generic error and correlate it with server logs. Details that help an attacker or leak data do not belong in the response.
Is 401 the same as 403?
401 means the request lacks valid authentication; 403 means the server understood the identity but refuses the action. Use the distinction consistently.
Can status codes replace documentation?
No. Document state, error codes, retry rules, and examples; status codes are one part of the contract.