HTTP Status Code List

How the HTTP Status Codes works

HTTP status code list: the five classes

Every HTTP response opens with a three-digit number, and the first digit alone tells you who has the problem. That single fact resolves most debugging sessions faster than reading the body: a 4xx means the request was wrong and sending it again unchanged will fail identically, while a 5xx means the request was fine and the server broke, so a retry with backoff is reasonable.

The 2xx family is less uniform than it looks. A 200 carries a body; a 204 deliberately does not, which makes it the right answer to a DELETE or to a PUT where the client already knows what it wrote. A 201 should always carry a Location header pointing at the thing that was created, and a 202 promises only that the work was queued — a client that treats it as completion will show users a success message for something that has not happened yet.

The redirect codes divide on a detail that breaks APIs. 301 and 302 historically allowed clients to change the method to GET when following the redirect, so a POST silently became a GET and the body vanished. 307 and 308 were added precisely to forbid that. If a redirect can ever apply to a non-GET request, use 307 or 308. And treat 301 with care: browsers and search engines cache it hard, sometimes indefinitely, so a permanent redirect sent by mistake is painful to undo.

The difference between 401 and 403 is the one people get wrong most. 401 means the server does not know who you are — no credentials, or credentials it could not verify — and by the specification it must include a WWW-Authenticate header saying how to authenticate. 403 means the server knows exactly who you are and is refusing anyway. Sending a 401 when the real problem is permissions makes clients retry the login loop forever.

400 and 422 split on syntax versus meaning. A body that is not valid JSON, or a request missing a required parameter, is a 400 — the server could not parse it. A body that parsed perfectly but whose values fail validation, like an email address without an at sign or a quantity of minus three, is a 422. Both are client errors, but the split tells the client whether to fix its serialiser or its data.

Rate limits and outages should always tell the client when to come back. 429 and 503 both carry a Retry-After header, in seconds or as a date, and honouring it is the difference between a system that recovers and one where every client retries in lockstep and keeps the server down. Add jitter to your backoff for the same reason.

502, 503 and 504 name three different failures that all look like "the site is down". A 502 means the proxy reached your application and got something invalid back — usually a crash. A 503 means the application deliberately declined, generally because it is overloaded or in maintenance. A 504 means the proxy gave up waiting entirely. Knowing which one you got points at which layer to look in first.

Related tools