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 a Location header.
  • 202 Accepted — the request was accepted for asynchronous processing; the work is not done.
  • 204 No Content — success with no body, common for DELETE and PUT.
  • 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 to GET in 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.