HTTP Status Codes You Misuse, and What to Return Instead
401 vs 403, 301 vs 308, 404 vs 410, 502 vs 503 vs 504. Picking the right status code tells clients and monitors what to do next.
On this page
Plenty of APIs answer every error with 200 and a JSON message, or every failure with 500. Clients then have to parse prose to decide whether to retry, re-authenticate or stop. The right status code makes that decision for them, and makes your dashboards honest.
The five classes
- 1xx Informational: the request was received and processing continues (for example 100 Continue).
- 2xx Success: it worked (200 OK, 201 Created, 204 No Content).
- 3xx Redirection: the client must take another step, such as following a redirect.
- 4xx Client error: the request is at fault. Retrying unchanged will not help.
- 5xx Server error: the server failed a valid request. Retrying may help.
That 4xx versus 5xx split is the most important idea. It decides whether an alert pages you and whether a client retries.
The pairs people confuse
Codes that make clients behave better
- 201 Created with a
Locationheader after creating a resource, so clients know where it lives. - 204 No Content for successful deletes or updates with nothing to return.
- 409 Conflict when the request clashes with current state, like a duplicate username or an edit conflict.
- 429 Too Many Requests with a
Retry-Afterheader, so well-behaved clients back off instead of hammering you. - 503 Service Unavailable with
Retry-Afterduring planned maintenance, so crawlers and clients know it is temporary and not a dead site.
A 200 with {"error": "not found"} in the body breaks caches, retries, monitoring and SEO crawlers, which all trust the status line. Reserve the body for detail, and put the truth in the status code.
A debugging cheat sheet
| You see | First suspicion |
|---|---|
| 401 on a request that worked yesterday | Expired token or clock skew |
| 403 only for some users | Authorization rules, roles, IP allow lists |
| 404 for a route you just deployed | Wrong path, trailing slash, routing config not deployed |
| 429 under load | Per-key rate limit hit, missing backoff in the client |
| 502 intermittently | An upstream process crashing or restarting |
| 503 during deploys | No graceful shutdown or readiness check |
| 504 on slow endpoints | Upstream slower than the proxy timeout |
Do
Return the most specific code that is true, include a machine-readable error body, and make 5xx mean “our fault” so alerts mean something.
Don't
Return 500 for validation errors or 404 for permission failures to “hide” resources without a reason. You will page yourself for client mistakes and confuse every integrator.
Takeaway
A status code is the cheapest, most widely understood contract in your API. Get the class right (client or server fault), then the specific code, and clients, proxies, crawlers and your own monitoring all do the right thing without reading a word of your error message.
Frequently asked questions
What is the difference between 401 and 403?
401 Unauthorized means authentication is missing or invalid: the server does not know who you are. 403 Forbidden means the server knows who you are and you are not allowed to do this. Retrying with valid credentials can fix a 401. Retrying the same identity on a 403 will not.
When should an API return 400 versus 422?
400 means the request is malformed in a way the server could not parse, such as broken JSON. 422 Unprocessable Content means the request was well-formed but failed semantic validation, like an invalid email or a negative quantity. Many APIs use 400 for both, but separating them helps clients.
What is the difference between 502, 503 and 504?
502 Bad Gateway means a proxy got an invalid response from the upstream. 503 Service Unavailable means the server is temporarily unable to handle the request, such as overload or maintenance. 504 Gateway Timeout means the proxy gave up waiting on the upstream. Together they tell you whether the upstream broke, is overloaded, or is slow.
Should I use 301 or 308 for a permanent redirect?
Both are permanent. The difference is method handling: 301 historically lets clients change POST to GET on the redirected request, while 308 requires the same method and body to be preserved. Use 308 when the method must not change, and 301 for ordinary page moves.



/* Comments */
Comments are offline right now — we reconnect automatically, nothing is lost.