A complete, searchable reference of every standard HTTP status code across all five categories (1xx–5xx), with its meaning and when to use it. Filter by category or search by code or keyword.
63 codes found
The server has received the request headers and the client should proceed to send the request body.
When to use: Sent by a server in response to an Expect: 100-continue header, letting a client know it's safe to send a large request body before the server commits to processing it.
The server is complying with a client's request to switch protocols, most commonly to WebSocket.
When to use: Returned when a client sends an Upgrade header (for example, to open a WebSocket connection) and the server agrees to switch to that protocol.
A WebDAV request has been received and is being processed, but no response is available yet.
When to use: Used by WebDAV servers to prevent a client from timing out while a request that involves many sub-requests is still being processed.
Used to return preload or preconnect hints while the server is still preparing the final response.
When to use: Sent before the final response so a browser can start fetching linked resources (like CSS or fonts) earlier, improving perceived page load time.
The request succeeded, and the response body contains the requested resource or result.
When to use: The default, general-purpose success response for GET, PUT, and POST requests that complete successfully and return content.
The request succeeded and a new resource was created as a result, typically returned from a POST.
When to use: Return this after successfully creating a new resource (a new user, a new record), usually alongside a Location header pointing to the new resource's URL.
The request has been accepted for processing, but that processing hasn't completed yet.
When to use: Used for asynchronous operations — the server has queued the work (like a background job or bulk export) but the result isn't ready to return immediately.
The request succeeded, but the returned metadata came from a proxy or cache rather than the origin server.
When to use: Returned by a transforming proxy that modifies the origin server's response headers or body before passing it along.
The request succeeded but there's no content to return in the response body.
When to use: Common for successful DELETE requests, or PUT/POST requests where the client doesn't need any data back beyond confirmation of success.
The request succeeded and the client should reset the document view that sent the request.
When to use: Used to tell a browser to clear a form after a successful submission, so the user can enter another entry without manually clearing fields.
The server is delivering only part of the resource due to a Range header sent by the client.
When to use: Returned for range requests — resuming a paused download, or streaming video where the player requests specific byte ranges.
Conveys information about multiple independent operations in a single WebDAV response.
When to use: Used by WebDAV when a single request (like a batch operation) produces multiple, individually-reportable results.
The members of a WebDAV binding have already been enumerated in a previous part of the response.
When to use: Used inside a 207 Multi-Status response to avoid repeatedly listing the same resource multiple times.
The server fulfilled the request using one or more instance-manipulations applied to the current instance.
When to use: Used with HTTP delta encoding, where the response represents a result of applying instance manipulations to the current resource.
The request has more than one possible response, and the client should choose one.
When to use: Rarely used in practice — applicable when a server can offer several representations of the same resource (different formats or languages) and lets the client pick.
The resource has permanently moved to a new URL, given in the Location header.
When to use: Use for permanent URL changes — a page redesign, a domain migration — so browsers and search engines update their records and pass along SEO value.
The resource temporarily resides at a different URL, given in the Location header.
When to use: Use for temporary redirects, such as sending a user to a login page before returning them to the page they originally requested.
The response to the request can be found at another URL using a GET request.
When to use: Commonly used after a POST to redirect the client to a confirmation or results page, preventing accidental form resubmission on refresh (the Post/Redirect/Get pattern).
The resource hasn't changed since the version specified by request headers, so no body is sent.
When to use: Returned in response to conditional GET requests (using If-None-Match or If-Modified-Since) to let a client reuse its locally cached copy.
The requested resource must be accessed through the proxy given in the response.
When to use: Deprecated for security reasons and no longer used by modern browsers — avoid relying on this status code.
Reserved by the original HTTP/1.1 specification; no longer used.
When to use: Not used by any current standard — reserved purely for historical reasons.
The resource temporarily resides at a different URL, and the request method must not change on redirect.
When to use: Use instead of 302 when it's important that a redirected POST request stays a POST rather than being converted to a GET by the client.
The resource has permanently moved, and the request method must not change on redirect.
When to use: Use instead of 301 when the redirected request's method (like POST) must be preserved exactly, unlike 301 which some clients may convert to GET.
The server can't process the request due to a client error — malformed syntax or invalid data.
When to use: Return when the request itself is malformed or fails validation — invalid JSON, a missing required field, or an out-of-range value.
Authentication is required and has either failed or not been provided.
When to use: Return when a request lacks valid authentication credentials — despite the name, this is about authentication, not authorization.
Reserved for future use; originally intended for digital payment systems.
When to use: Rarely used per its original intent, but some APIs repurpose it to indicate a subscription or billing issue is blocking the request.
The server understood the request but refuses to authorize it.
When to use: Return when a client is correctly authenticated but doesn't have permission to access the specific resource or perform the action.
The server can't find the requested resource.
When to use: The standard response for a URL or resource that doesn't exist — also commonly used deliberately to hide the existence of a resource from unauthorized users.
The request method is known by the server but isn't supported for this specific resource.
When to use: Return when, for example, a client sends a DELETE request to an endpoint that only supports GET and POST.
The server can't produce a response matching the Accept headers sent by the client.
When to use: Return when content negotiation fails — a client requests a response format (via the Accept header) the server simply can't provide.
Similar to 401, but authentication must happen with a proxy first.
When to use: Returned by an intermediary proxy server that requires its own separate authentication before forwarding the request onward.
The server timed out waiting for the client to send a complete request.
When to use: Returned when a client opens a connection but is too slow sending the full request, so the server gives up waiting.
The request conflicts with the current state of the target resource.
When to use: Return for edit conflicts, like two clients trying to update the same resource simultaneously with incompatible versions.
The requested resource is no longer available and has been permanently removed, with no forwarding address.
When to use: Use instead of 404 when you specifically know a resource used to exist but was deliberately, permanently deleted — helps search engines deindex it faster.
The server requires a Content-Length header, which the request didn't include.
When to use: Returned when a server needs to know the request body's size upfront and the client omitted the Content-Length header.
One or more conditions in the request's header fields evaluated to false.
When to use: Returned when a conditional request (using If-Match or similar headers) fails its precondition check, often used to prevent overwriting newer data.
The request body is larger than the server is willing or able to process.
When to use: Return when a client uploads a file or payload that exceeds the server's configured size limit.
The URI requested by the client is longer than the server is willing to interpret.
When to use: Returned when a client sends an excessively long URL, often the result of a poorly constructed GET request with too much data in query parameters.
The request's payload format (its Content-Type) isn't supported by the server.
When to use: Return when, for example, a client sends XML to an API endpoint that only accepts JSON.
The range specified by the Range header can't be fulfilled for the target resource.
When to use: Returned when a client requests a byte range (for resuming a download) that's outside the actual bounds of the resource.
The server can't meet the requirements of the Expect header sent in the request.
When to use: Returned when a client sends an Expect: 100-continue header and the server can't or won't honor that expectation.
A humorous, non-standard status code originating from an April Fools' RFC about a teapot refusing to brew coffee.
When to use: Not intended for real production use — occasionally implemented as an Easter egg, or referenced humorously in documentation and testing.
The request was directed at a server that can't produce a response for the requested URI.
When to use: Occurs with connection reuse and HTTP/2, when a request lands on a server that isn't actually configured to handle the requested host.
The request is well-formed but contains semantic errors that prevent it from being processed.
When to use: Widely used by APIs for validation errors — the JSON syntax is valid, but a field fails a business rule (like an invalid email format).
The resource being accessed is locked.
When to use: Used by WebDAV when a resource has an active lock preventing the current operation from proceeding.
The request failed because a previous, related request also failed.
When to use: Used by WebDAV when one operation in a sequence depends on another operation that didn't succeed.
The server is unwilling to process a request that might be replayed.
When to use: Used to reject requests sent using TLS 0-RTT (early data) where a replay attack risk exists.
The server refuses to process the request using the current protocol but might if the client upgrades.
When to use: Returned when a server requires a newer protocol version, such as requiring a plain HTTP client to switch to TLS.
The origin server requires the request to be conditional.
When to use: Used to force clients to use conditional requests (with If-Match), preventing the 'lost update' problem when multiple clients edit the same resource.
The client has sent too many requests in a given period of time (rate limiting).
When to use: Return when a client exceeds an API's rate limit, typically alongside a Retry-After header telling the client when to try again.
The server refuses to process the request because its header fields are too large.
When to use: Returned when a request's cumulative headers (including cookies) exceed a server's configured size limit.
The resource is unavailable due to a legal demand, such as a government-mandated content block.
When to use: Use when access to a resource has been intentionally blocked in response to a legal order, such as a censorship demand or DMCA takedown.
A generic error indicating the server encountered an unexpected condition.
When to use: The catch-all response for unhandled exceptions and unexpected server-side failures that don't fit a more specific error code.
The server doesn't support the functionality required to fulfill the request.
When to use: Return when a server doesn't recognize the request method at all, or hasn't implemented a specific feature yet.
A server acting as a gateway or proxy received an invalid response from an upstream server.
When to use: Common when a reverse proxy or load balancer can't get a valid response from a backend application server (often because it crashed or is restarting).
The server is currently unable to handle the request, typically due to overload or maintenance.
When to use: Return during planned maintenance windows or when a server is temporarily overloaded, ideally alongside a Retry-After header.
A server acting as a gateway didn't receive a timely response from an upstream server.
When to use: Common when a backend service takes too long to respond to a reverse proxy or load balancer, which then gives up waiting.
The server doesn't support the HTTP protocol version used in the request.
When to use: Rarely encountered in practice — returned if a client requests using an HTTP version the server has no support for at all.
The server has an internal configuration error involving transparent content negotiation.
When to use: Occurs only with server-side content negotiation misconfiguration where a chosen variant itself points back into further negotiation.
The server is unable to store the representation needed to complete the request.
When to use: Used by WebDAV when the server has run out of storage space needed to fulfill the request.
The server detected an infinite loop while processing the request.
When to use: Used by WebDAV when processing a request would result in an infinite loop, such as a circularly-referencing set of bindings.
Further extensions to the request are required for the server to fulfill it.
When to use: Rarely used — indicates the client needs to negotiate additional policies (HTTP extensions) with the server before the request can succeed.
The client needs to authenticate to gain network access, often used by captive portals.
When to use: Returned by network infrastructure (like public Wi-Fi captive portals) that intercepts traffic until the user logs in or accepts terms.
Every HTTP response includes a three-digit status code that tells the client, in a single standardized number, the outcome of its request — whether it succeeded, needs to look elsewhere, was rejected due to a client mistake, or failed because of a server problem. This standardization is what lets browsers, API clients, monitoring tools, and load balancers all react correctly to any HTTP response without needing to parse and understand the specific application's response body — a monitoring tool can flag every 5xx response as a server-side incident, a browser can automatically follow every 3xx redirect, and an API client library can automatically retry every 503 after the specified delay, all based purely on the numeric code.
HTTP status codes are organized into five classes based on their first digit, defined originally in RFC 7231 and its predecessors. This isn't arbitrary — it's a deliberate design that lets any client make a reasonable fallback decision even for a status code it doesn't specifically recognize, simply by checking which class it belongs to: an unrecognized 4xx code should still be treated as a client-side problem worth surfacing to the user, and an unrecognized 2xx code should still be treated as success. Within each class, individual codes add more specific meaning — 200 versus 201 versus 204 all indicate success, but communicate meaningfully different things about exactly what happened and what the response body will (or won't) contain.
Picking an accurate, specific status code — rather than defaulting to a generic 200 for everything or 500 for every error — makes an API dramatically easier for other developers to integrate with, since well-chosen status codes let client code branch correctly (retry on 503, don't retry on 400, prompt for login on 401) without needing to parse and interpret a custom error message format. A useful discipline: reserve 2xx exclusively for genuine success, use the specific 4xx code that best describes what the client did wrong (400 for malformed syntax, 401 for missing/invalid auth, 403 for a genuine permission denial, 404 for a resource that doesn't exist, 409 for a conflicting state, 422 for a failed validation rule, 429 for rate limiting), and reserve 5xx strictly for problems that are genuinely the server's fault, not the client's.
Certain status codes carry consequences well beyond a single request-response exchange. 301 Moved Permanently tells search engines to transfer a page's accumulated SEO ranking to its new URL, while 302 Found deliberately doesn't, which is why using the wrong one for a permanent site restructuring can cost real search ranking. 304 Not Modified, returned in response to a conditional request, lets a browser reuse its local cache instead of re-downloading unchanged content, meaningfully improving page load performance at scale. 410 Gone tells search engines a resource was deliberately, permanently removed (rather than temporarily missing, as 404 implies), which typically causes faster deindexing than a plain 404 would. Choosing the semantically correct code in each of these cases has real, measurable downstream effects beyond just satisfying the immediate request.
When something goes wrong in a distributed system — a web app calling an API, an API calling a database or third-party service — the status code returned at each hop is often the fastest available clue for narrowing down where the actual failure occurred. A 502 or 504 from your own reverse proxy typically points to a problem with your backend application rather than the proxy itself; a 429 means you're hitting a rate limit somewhere in the chain, not a genuine failure; a 401 versus 403 tells you immediately whether to check authentication configuration or authorization/permissions logic. Learning to read status codes precisely — rather than treating 'it's not a 200' as one undifferentiated failure state — is one of the fastest ways to speed up debugging any HTTP-based system.
HTTP Status Codes Reference is a lookup tool for every standard response code. These related developer tools cover other parts of building and debugging HTTP-based APIs.