---
topic: dev-practices
author: Crashtech Editorial
published: Nov 13, 2026 · read: 3 min
---

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.

– –

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

401 vs 403 who are you vs not allowed
401: authentication is missing or invalid, log in and try again. 403: you are identified but not permitted, logging in again changes nothing.
400 vs 422 malformed vs invalid
400: the request could not be parsed (broken JSON). 422: it parsed fine but failed validation (bad email, negative quantity).
404 vs 410 not found vs gone
404: nothing here, maybe never. 410: it existed and was removed on purpose. Search engines drop 410 pages faster.
301 vs 308 method handling
Both permanent. 308 forces the client to repeat the same method and body. Use it when redirecting a POST endpoint.
302 vs 307 temporary redirects
Both temporary. 307 preserves the method and body, 302 may not. Prefer 307 for API redirects.
502 vs 503 vs 504 where it failed
502: upstream sent garbage. 503: server overloaded or in maintenance. 504: upstream took too long. Three different incidents.

Codes that make clients behave better

  • 201 Created with a Location header 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-After header, so well-behaved clients back off instead of hammering you.
  • 503 Service Unavailable with Retry-After during planned maintenance, so crawlers and clients know it is temporary and not a dead site.
Never return 200 for an error

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.

Advertisement

A debugging cheat sheet

You seeFirst suspicion
401 on a request that worked yesterdayExpired token or clock skew
403 only for some usersAuthorization rules, roles, IP allow lists
404 for a route you just deployedWrong path, trailing slash, routing config not deployed
429 under loadPer-key rate limit hit, missing backoff in the client
502 intermittentlyAn upstream process crashing or restarting
503 during deploysNo graceful shutdown or readiness check
504 on slow endpointsUpstream 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.

Advertisement

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.

Sources & further reading

/* Comments */