HTTP status codes explained: every code you'll actually see

An HTTP status code is a three-digit number a server returns with every response, telling the client whether the request succeeded — and if not, why. Codes are grouped into five classes, and once you know the class, you already know most of the story.

The five classes

2xx: it worked

• 200 OK — the request succeeded. For GET, the resource is in the response body; for POST/PUT, the result of the action is transmitted.
• 201 Created — a new resource was created, typically after a POST or some PUT requests.
• 202 Accepted — the request was received but not yet acted upon; useful when another process or server handles it, or for batch processing.
• 204 No Content — there is no content to send, but the headers are useful; the client may update its cached headers.

3xx: look over here

• 301 Moved Permanently — the URL changed permanently; the new URL is in the response. Browsers and search engines update their links.
• 302 Found — the URI changed temporarily; the client should keep using the same URI for future requests.
• 304 Not Modified — used for caching: the response has not changed, so the client can keep using its cached version.
• 307 Temporary Redirect — like 302, but the method must not change: a POST stays a POST.
• 308 Permanent Redirect — like 301, but the method must not change either.

4xx: your fault (mostly)

• 400 Bad Request — the server cannot process the request due to a client error, like malformed syntax or invalid framing.
• 401 Unauthorized — the name is misleading: semantically it means unauthenticated. The client must prove who it is.
• 403 Forbidden — the client is known, but has no right to access the content.
• 404 Not Found — the server cannot find the requested resource. In a browser this means the URL is not recognized; in an API the endpoint can be valid while the resource does not exist. Servers may also send 404 instead of 403 to hide a resource's existence.
• 405 Method Not Allowed — the method is known but not supported by the target resource, e.g. an API that does not allow DELETE on a resource.
• 408 Request Timeout — an idle connection the server wants to shut down.
• 409 Conflict — the request conflicts with the current state of the server.
• 410 Gone — the content was permanently deleted with no forwarding address; clients should drop their caches and links. Intended for limited-time, promotional resources — APIs need not use it for every deleted resource.
• 418 I'm a teapot — the server refuses to brew coffee with a teapot. Yes, this is a real, standardized code, kept for its humor and history.
• 429 Too Many Requests — rate limiting: too many requests in a given time.

5xx: the server's fault

• 500 Internal Server Error — the server hit a situation it does not know how to handle; the generic code used when nothing more specific fits.
• 501 Not Implemented — the request method is not supported by the server. GET and HEAD are the only methods servers must support.
• 502 Bad Gateway — a server acting as a gateway got an invalid response from the upstream server.
• 503 Service Unavailable — the server is not ready: down for maintenance or overloaded. A user-friendly page should be sent along, and the temporary condition should usually not be cached.
• 504 Gateway Timeout — a server acting as a gateway could not get a response in time.
• 511 Network Authentication Required — the client must authenticate to gain network access (think captive portals).

How to read a code you've never seen

If a response is not in the standard list, it is non-standard, possibly custom to the server's software. The class digit still tells you the shape of the story: 1xx means keep waiting, 2xx means it worked, 3xx means redirected, 4xx means the client should fix something, 5xx means the server is failing. That rule of thumb survives even the oddest custom code.

FAQ

What does a 404 Not Found mean?

A 404 means the server cannot find the requested resource. In a browser it means the URL is not recognized; in an API the endpoint can be valid while the resource does not exist. Servers may also send 404 instead of 403 to hide a resource's existence.

What is the difference between 301 and 308?

A 301 Moved Permanently means the URL changed permanently and the new URL is in the response, with browsers and search engines updating their links. A 308 Permanent Redirect works like 301, but keeps the HTTP method unchanged: a POST stays a POST.

What is the difference between 401 Unauthorized and 403 Forbidden?

A 401 means the client is not authenticated — it has to prove who it is (the name is misleading). A 403 means the client is known, but has no right to access the content. In short: 401 is about missing identity, 403 about missing permission.

Why am I seeing a 503 Service Unavailable?

A 503 means the server is not ready to handle the request, typically because it is down for maintenance or overloaded. A user-friendly page should be sent along, and the temporary condition should usually not be cached.

Summary

Status codes are the HTTP way of answering "how did that go?" — five classes covering every outcome from "still working" to "server on fire". The codes you will actually meet are few: 200, 201, 301, 304, 404, 429, 500, 502, 503, 504. Recognize those and you can read any API response or server log with confidence.