Most explanations of HTTP status codes are lists: 200 means OK, 404 means Not Found. The lists are correct but miss the point. A status code is the server telling the client, in one number, what kind of thing just happened and therefore what the client should do next. Retry? Fix the request? Ask the user to log in? Give up? If you think of status codes as answers to “what now?”, choosing the right one becomes much easier.

The first digit does most of the work

Every code falls into a class determined by its first digit. Clients, proxies, load balancers and monitoring tools often look only at that digit, so getting the class right matters more than picking the perfect code within it.

  • 2xx, success. The request did what was asked. Move on.
  • 3xx, redirection. Look elsewhere, or use what you already have.
  • 4xx, client error. Something about your request is wrong. Sending the identical request again will fail again.
  • 5xx, server error. Your request may have been fine; the server failed. Trying again later might work.

That 4xx versus 5xx split is the single most consequential distinction. It decides whether automatic retry logic kicks in, whether an on-call engineer gets paged (5xx rates usually drive alerts), and who is to blame in a dispute between two teams.

The success codes, and why the distinctions matter

200 OK is the general success response, usually with a body. 201 Created says a new resource now exists; it should come with a Location header pointing to that resource, so the client knows where to find it. 202 Accepted says “I have received this and will process it later”, which is the honest response for anything queued, such as generating a large report. 204 No Content means success with nothing to return, typical after a delete.

The difference between 200 and 202 is not pedantry. A client that gets 200 for a bulk import assumes the import has finished. If it actually only queued, the client will show users data that is not there yet.

401 versus 403: two very different problems

These two are confused more than any others, partly because 401’s official name, “Unauthorized”, is misleading.

401 really means unauthenticated: the server does not know who you are. The token is missing, expired or invalid. The right client reaction is to refresh the token or send the user to the login screen. The specification expects a WWW-Authenticate header with it, describing how to authenticate.

403 Forbidden means the server knows exactly who you are, and you are not allowed to do this. A sales executive trying to open the payroll export gets 403. Logging in again will not help; the client should show a “you don’t have access” message, not a login prompt.

Return 401 when you mean 403 and the front end may loop forever: refresh token, retry, 401, refresh again.

There is a deliberate exception. If merely confirming that a resource exists would leak information, servers often return 404 instead of 403. Asking for invoice 10452 belonging to another company should usually say “not found” rather than “that exists but it’s not yours”, because the second answer lets someone enumerate other customers’ invoice numbers.

The other client errors worth knowing

CodeMeaningWhat the client should do
400 Bad RequestMalformed request: broken JSON, missing required fieldFix the request; do not retry as is
404 Not FoundNo such resource (or none you may know about)Check the identifier
409 ConflictRequest clashes with current state, e.g. booking a seat someone just tookRefresh state, then decide
422 Unprocessable ContentWell-formed but fails business validation, e.g. a date of birth in the futureShow validation messages
429 Too Many RequestsRate limit exceededWait, ideally as long as Retry-After says

Teams differ on whether validation failures should be 400 or 422. Either is defensible; what matters is being consistent across your APIs and returning a body that explains which field failed and why.

Server errors: who failed, and where

500 Internal Server Error is the catch-all for an unhandled failure: a null pointer, an unexpected exception. Seeing a lot of 500s means your code has bugs. 502 Bad Gateway and 504 Gateway Timeout come from a proxy or load balancer in front of your application: the upstream returned garbage, or did not answer in time. 503 Service Unavailable means the server is deliberately refusing for now, during maintenance or overload, and may include Retry-After.

These distinctions speed up incident diagnosis. A spike in 504s points at slow dependencies or database queries. A spike in 502s often points at application instances crashing or restarting. A spike in 500s points at a recent deployment.

The 200-for-everything anti-pattern

Some APIs return 200 for every response and put the real outcome in the body, such as a field saying success is false. It seems harmless, but it breaks everything that relies on the status line. Load balancer health metrics report 100% success during an outage. Caches may store error responses as if they were valid. Retry logic never fires. Every client must parse the body to know whether anything worked.

The opposite mistake is returning 500 for client mistakes, for example when a validation exception escapes uncaught. Now a user typing a bad PIN code triggers alerts meant for outages, and retrying clients hammer the server with requests that will never succeed.

A good rule: pick the code that tells a well-written client the correct next step, then put the human-readable detail in the body. RFC 9457, “Problem Details for HTTP APIs”, defines a standard JSON shape for that body with fields such as type, title, status and detail, and is worth adopting if your team has no convention yet.

Written by the RP Strativa Team.

Leave a Reply

Trending