REST and HTTP have been around for decades, but the way we use status codes in production often lags behind. Many teams treat the response code as an afterthought: they return 200 for everything and put the real outcome in the body. Others overload 400 or 500 with dozens of different error cases. Both approaches make it harder for clients, gateways, and monitoring systems to behave correctly. This piece looks at why status codes still matter and how to use them consistently.
HTTP status codes are part of the contract of the protocol. Clients and intermediaries are allowed to make decisions based on the numeric code alone—whether to retry, cache, or show an error. When you always return 200 and encode success or failure only in the body, you break that contract. Load balancers and CDNs may cache responses that should not be cached. Retry logic may not trigger when it should. Monitoring and alerting become harder because you cannot rely on the code to classify success vs. client error vs. server error. Using the right code does not require a PhD; it requires a bit of consistency and a good reference.
The Three Buckets That Matter
In practice, three buckets cover most of what you need. 2xx means the request was understood and handled successfully. 4xx means the client sent something invalid or not allowed; the client should change the request, not retry blindly. 5xx means the server or something it depends on failed; the client may retry later. Within those, a few codes do most of the work: 200 (OK), 201 (Created), 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), and 500 (Internal Server Error). For APIs that sit behind gateways or proxies, 502 (Bad Gateway) and 503 (Service Unavailable) also show up often. Knowing when to use each one helps clients and operators reason about failures without parsing your custom error payloads.
Choosing the wrong bucket has downstream effects. If you return 200 for a validation error, client SDKs that branch on response.ok will treat it as success and may not surface the error to the user. If you return 500 for a bad request, retry logic may hammer your server with the same invalid payload. Gateways and proxies often treat 5xx differently from 4xx—for example, marking a backend as unhealthy after repeated 5xx or applying backoff.
Real-World Consequences
Consider a mobile app that gets a 500 for a failed payment. If the server had returned 400 with a clear body, the app could show “check your card details” and not retry. With 500, the app might retry repeatedly or show a generic “something went wrong” message. Similarly, a health check that returns 200 even when a dependency is down will keep receiving traffic until the whole service fails. Returning 503 when the service is degraded allows load balancers to stop sending new requests and gives clients a signal to back off. These behaviors are only possible when the status code is used correctly. A single, well-maintained HTTP status code reference makes it easier for teams to agree on which code to use in each situation.
In distributed systems, status codes propagate. A backend returns 503; the API gateway may pass it through or convert it to 502. A CDN may cache 200 but not 5xx. If your service returns 200 for "temporarily unavailable," the gateway has no signal to stop sending traffic or to fail over. Documenting which codes your API returns—and training the team on when to use each—reduces surprises in production and makes incident response faster.
Small Habits That Help
A few habits go a long way. First, decide per endpoint which codes you will use (e.g. 200, 201, 400, 401, 404, 500) and document them in your API spec. Second, avoid overloading 400: use 401 for auth problems, 403 for forbidden, 404 for missing resources. Third, reserve 5xx for real server or dependency failures, and use 503 when the service is intentionally unavailable (e.g. maintenance). Fourth, use a consistent error body (e.g. RFC 7807) so that when the code says “client error” or “server error,” the body adds detail without contradicting the code. Over time, this consistency makes debugging and monitoring much simpler.
Add status codes to code review checklists: "Does this endpoint return the right code for success and for each error case?" Write tests that assert on status as well as body—for example, "POST with invalid payload returns 400, not 200." When you add a new error case, ask: "Is this a client mistake (4xx) or a server failure (5xx)?" That discipline, applied consistently, pays off when you're debugging at 2 a.m. or onboarding a new client team.
HTTP status codes are not legacy trivia. They are the first thing clients and infrastructure look at. Using them deliberately improves reliability, observability, and the experience of anyone integrating with your API.
Top comments (0)