A status code is a machine-readable summary of what happened. Clients, proxies, crawlers and monitoring systems act on the number before they read the body. Returning the wrong one is not a cosmetic issue; it changes how the response is cached, retried and displayed.
Start with the class
| Class | Meaning | Who acts |
|---|---|---|
| 2xx | Success | Nobody; the request worked |
| 3xx | Redirection | The client follows or updates the URL |
| 4xx | Client error | The caller must change the request |
| 5xx | Server error | The server or operator must act |
The class narrows the choice. The specific code explains what kind of success or failure it was.
Success is not always 200
200 OK— a normal response with a body.201 Created— a resource was created; include aLocationheader.202 Accepted— the request was accepted for asynchronous processing; the work is not done.204 No Content— success with no body, common forDELETEandPUT.206 Partial Content— a range request succeeded.
A DELETE that returns 200 with {"ok":true} is valid, but 204 is cleaner: there is nothing to say. Be consistent within an API.
Redirects: permanent versus temporary
301 Moved Permanently— cacheable; crawlers update their index. Use only when the old URL is gone forever.302 Found— temporary; clients may change the method toGETin practice.307 Temporary Redirect— temporary and preserves the method and body.308 Permanent Redirect— permanent and preserves the method.
The 301/302 pair is about permanence; 307/308 are about method preservation. For a POST endpoint that moved, 307 or 308 avoids the silent conversion to GET that 302 can cause.
Client errors: be precise
| Code | Use it when |
|---|---|
| 400 | The request is malformed: bad JSON, missing required field |
| 401 | Authentication is missing or invalid |
| 403 | Authenticated, but not allowed |
| 404 | The resource does not exist (or you are hiding it) |
| 405 | The path exists, the method does not; include Allow |
| 409 | The request conflicts with current state, such as a duplicate |
| 412 | A precondition such as If-Match failed |
| 415 | The media type is unsupported |
| 422 | The syntax is valid but the semantics fail validation |
| 429 | A rate limit was exceeded; include Retry-After |
The 401/403 distinction is the most common interview question and the most common production mistake. 401 means “I do not know who you are”; 403 means “I know who you are, and you cannot do this”. Retrying a 403 with the same credentials will never succeed.
400 versus 422 is a matter of convention. Some APIs use 400 for all validation failures; others reserve 400 for malformed syntax and 422 for semantic validation. Pick one and document it.
Server errors: do not leak details
500 Internal Server Error— an unexpected failure.502 Bad Gateway— an upstream returned an invalid response.503 Service Unavailable— overloaded or in maintenance; often retryable.504 Gateway Timeout— an upstream did not respond in time.
The response body for a 5xx should not contain a stack trace, SQL, or internal hostnames. Log the details server-side and return a correlation ID.
Retry semantics
| Code | Retry? | Notes |
|---|---|---|
| 408 | Yes | The client timed out; retry with backoff |
| 429 | Yes | Honor Retry-After |
| 500 | Maybe | Only idempotent requests, bounded attempts |
| 502 | Yes | Usually transient |
| 503 | Yes | Honor Retry-After |
| 504 | Yes | But the upstream may have processed the request |
The last row is the dangerous one. A gateway timeout does not prove the upstream did nothing. Retrying a non-idempotent POST after a 504 can duplicate a charge or an order. Use idempotency keys for anything that matters.
Caching and status codes
200, 301, 304, 404 and 410 are cacheable by default in many configurations; 500 and 503 are not. A 304 Not Modified relies on ETag or Last-Modified and must not include a body. If you return 200 with an unchanged body, you lose the bandwidth savings; if you return 304 without validators, clients may cache incorrectly.
Consistency beats cleverness
A public API should document its status-code policy: which codes each endpoint returns, what the body looks like for errors, and whether retries are safe. Clients should branch on the code, not on parsing an error message. If the code is 200 for every outcome, the contract is effectively gone.
The HTTP status code reference is searchable by code, name and meaning. Individual pages cover the common confusions in detail, including 401 vs 403 and 502 vs 503 vs 504.