HTTP Status Codes

HTTP status codes are three-digit numbers a server sends back with every response to say what happened to the request. The first digit gives the class — 1xx informational, 2xx success, 3xx redirection, 4xx client error, 5xx server error — and the remaining two identify the specific condition. They are defined by RFC 9110 and registered with IANA, so the same code means the same thing across every server and client that implements HTTP.

1xx Informational means the request was received and processing continues, with a final response still to come. 2xx Success means the request was received, understood and accepted. 3xx Redirection means further action is needed, usually following a new location or using a cached copy. 4xx Client Error means the request is faulty. 5xx Server Error means the server failed to fulfil an apparently valid request.

200 OK means the request succeeded. What the body contains depends on the method: for a GET it is the requested representation, for a POST it is the result of the action. It is the most common response on the web and the default for any successful request that has something to return.

201 Created means the request succeeded and one or more new resources were created as a result. The response should carry a Location header pointing at the new resource. It is the conventional reply to a POST that creates a record, though returning 200 with the created object is also common and equally valid.

204 No Content means the request succeeded and there is deliberately nothing to send back. The response must not include a body. It is typical for a successful DELETE, or for a PUT or PATCH where the client already knows the resulting state and does not need it echoed.

301 Moved Permanently means the resource has a new permanent URL, given in the Location header. Clients should update bookmarks and search engines should transfer ranking signals to the new address. Be aware that clients have historically changed a POST to a GET when following a 301 — use 308 Permanent Redirect when the method must be preserved.

302 Found means the resource is temporarily somewhere else and the original URL should continue to be used for future requests. Like 301, most clients change POST to GET when following it, which is why 303 See Other and 307 Temporary Redirect exist — they make the intended behaviour explicit instead of relying on convention.

400 Bad Request means the server will not process the request because something about it is malformed — broken syntax, an invalid message frame, or a body it could not parse. It is widely used as a general-purpose client error. When the syntax is fine but the content breaks the application's rules, 422 Unprocessable Content is more precise.

401 Unauthorized means the request lacks valid authentication credentials. The name is misleading: it is about authentication, not permission. A 401 response must include a WWW-Authenticate header telling the client how to authenticate. Common causes are a missing API token, an expired session, or an invalid login.

403 Forbidden means the server understood the request and refuses to authorise it. Unlike a 401, authenticating differently will not help — the client is known and still not allowed. Servers sometimes return 404 Not Found instead, to avoid confirming that a resource exists to someone not permitted to see it.

404 Not Found means the server has no current representation for the requested resource, and deliberately declines to say whether that is temporary or permanent. It covers mistyped URLs, deleted pages, missing API resources, and cases where a server is hiding a resource's existence from an unauthorised client.

405 Method Not Allowed means the server recognises the method but does not support it for this particular resource — a POST to a read-only endpoint, for example. The response must include an Allow header listing the methods that are supported, which makes it one of the more actionable errors to receive.

409 Conflict means the request clashes with the current state of the resource, in a way the client could potentially resolve and retry. Typical cases are creating a record that already exists, a duplicate value in a unique field, or two clients editing the same resource concurrently.

422 Unprocessable Content means the request was syntactically valid and the content type was understood, but the server cannot process the instructions inside it — most often a validation failure on a well-formed body. RFC 9110 moved it into core HTTP from WebDAV, where it was called Unprocessable Entity, and many libraries still use the old name.

429 Too Many Requests means the client has sent too many requests in a given period and is being rate limited. A well-behaved server includes a Retry-After header saying when to try again. It is defined by RFC 6585 rather than the core specification, and is the standard response for API throttling.

500 Internal Server Error means the server hit an unexpected condition and has nothing more specific to say. It is the catch-all server error, most often an unhandled exception. It tells you the fault is on the server side and nothing else — the detail will be in the server's logs, not the response.

502 Bad Gateway means a server acting as a gateway or proxy received an invalid response from the upstream server behind it. In practice it usually means the application server crashed, is not running, or returned something the proxy could not parse. The proxy is working; what is behind it is not.

503 Service Unavailable means the server cannot handle the request right now, typically because it is overloaded or down for maintenance, and the condition is expected to be temporary. It should carry a Retry-After header when the duration is known. Unlike 502, it is usually the server deliberately declining rather than failing.

504 Gateway Timeout means a gateway or proxy did not receive a response from the upstream server within the time it was willing to wait. The upstream may still be working on it — the proxy simply gave up. Common causes are slow database queries and requests that exceed a load balancer's timeout.

401 Unauthorized means the server does not know who you are — credentials are missing, expired or invalid, and supplying valid ones may fix it. 403 Forbidden means the server knows who you are and you still may not do this; re-authenticating will not help. The rule of thumb: 401 is about identity, 403 is about permission.

404 Not Found says the resource cannot currently be found, without committing to whether it ever existed or might return. 410 Gone says it was deliberately removed and is not expected to come back. 410 is a stronger signal — search engines drop 410 URLs from their indexes faster. Use 410 only when the removal is intentional and permanent; otherwise 404 is the safer answer.

All three come from a gateway or proxy in front of your application. 502 Bad Gateway means the upstream returned something invalid or refused the connection. 503 Service Unavailable means the server itself is unable to handle the request, usually through overload or maintenance. 504 Gateway Timeout means the upstream was reachable but did not answer in time. Roughly: 502 is broken, 503 is unavailable, 504 is too slow.

201 Created is the conventional answer, with a Location header pointing at the new resource. That said, no specification requires it — plenty of well-designed APIs return 200 OK with the created object, or 202 Accepted when creation is queued rather than immediate. What matters most is choosing one and applying it consistently across the API.

Yes, by classification. 4xx codes indicate the request cannot be fulfilled because of an apparent client-side problem, and a request for something that is not there qualifies. In practice the cause is often a stale link or a server-side deletion rather than any mistake by the person making the request — the class describes where the problem appears, not who is at fault.

Yes. Core HTTP status codes are defined by RFC 9110, with others in extension RFCs such as RFC 6585 for 428, 429 and 431, and RFC 4918 for the WebDAV codes. All registered codes are listed in the IANA HTTP Status Code Registry. Codes such as nginx's 499 or Cloudflare's 520 to 526 are not registered and are conventions of those specific products.