Complete reference of all HTTP status codes with descriptions and examples.
Showing 61 of 61
4 status codes
The server has received the request headers and the client should proceed to send the request body. This is used to optimize large uploads by letting the client check if the server will accept the request before sending the full payload.
Common Use Cases: Used when a client sends an Expect: 100-continue header before uploading a large request body, allowing the server to reject the request early without wasting bandwidth.
The server is switching to a different protocol as requested by the client via an Upgrade header. The server agrees and will communicate using the new protocol after this response.
Common Use Cases: Most commonly seen when upgrading an HTTP connection to a WebSocket connection. The client sends an Upgrade: websocket header and the server responds with 101 to confirm the switch.
The server has received and is processing the request, but no response is available yet. This prevents the client from timing out while the server works on a long-running operation.
Common Use Cases: Used in WebDAV operations that may take a long time to complete. Lets the client know the server has not dropped the connection and is still working on the request.
The server sends preliminary response headers before the final response. This allows the client to start preloading resources while the server is still preparing the full response.
Common Use Cases: Used to send Link headers early so the browser can preload CSS, JavaScript, or fonts before the final HTML response arrives, improving page load performance.
10 status codes
The request has succeeded. The meaning of the success depends on the HTTP method: GET returns the requested resource, POST returns the result of the action, and so on.
Common Use Cases: The standard success response for most API calls. Used when a GET request returns data, a PUT request updates a resource, or any operation completes successfully with a response body.
GET /api/users/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 42,
"name": "Jane Doe",
"email": "jane@example.com",
"created_at": "2025-08-15T10:30:00Z"
}The request has been fulfilled and a new resource has been created. The response typically includes a Location header pointing to the newly created resource.
Common Use Cases: Returned after a successful POST request that creates a new resource, such as creating a new user account, adding a blog post, or uploading a file.
POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
"name": "Jane Doe",
"email": "jane@example.com"
}HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/users/42
{
"id": 42,
"name": "Jane Doe",
"email": "jane@example.com",
"created_at": "2025-08-15T10:30:00Z"
}The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place.
Common Use Cases: Used for asynchronous operations where the server queues a task for later processing, such as sending an email, generating a report, or triggering a batch job.
The request was successful but the returned metadata in the headers may come from a local or third-party copy rather than the origin server. The enclosed payload is a modified version of the origin server's 200 response.
Common Use Cases: Rarely used in practice. Can appear when a transforming proxy modifies the response headers from the origin server, indicating the metadata may not match the original.
The server has successfully fulfilled the request and there is no additional content to send in the response payload body. The response may include updated headers.
Common Use Cases: Returned after a successful DELETE request, or a PUT/PATCH update where no response body is needed. Also used for fire-and-forget operations where acknowledgment alone is sufficient.
DELETE /api/users/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...HTTP/1.1 204 No ContentThe server has fulfilled the request and desires that the user agent reset the document view that caused the request to be sent. No response body is included.
Common Use Cases: Used to tell the client to reset the form or UI that submitted the request. For example, after successfully submitting a form, the server can signal the browser to clear the form fields.
The server is delivering only part of the resource due to a range header sent by the client. This is used for resumable downloads and media streaming.
Common Use Cases: Used when a client requests a specific byte range of a large file, enabling features like resumable downloads, video seeking, and parallel chunk downloads.
A WebDAV response that conveys information about multiple resources in situations where multiple status codes might be appropriate. The response body is an XML document containing individual status codes for each sub-request.
Common Use Cases: Used in WebDAV batch operations where each sub-operation may have a different outcome. For example, copying multiple files where some succeed and some fail.
Used inside a DAV: propstat response element to avoid enumerating the internal members of multiple bindings to the same collection repeatedly.
Common Use Cases: A WebDAV status used to avoid listing the same resource multiple times when it appears in multiple locations within a collection due to bindings.
The server has fulfilled a GET request for the resource, and the response is a representation of the result of one or more instance-manipulations applied to the current instance.
Common Use Cases: Used with delta encoding to send only the changes (deltas) between the current version of a resource and a previously cached version, reducing bandwidth usage.
7 status codes
The target resource has more than one representation and the user or user agent can select a preferred one. The server may include a list of available representations.
Common Use Cases: Rarely used in practice. Could be used when a resource is available in multiple formats (e.g., JSON, XML, HTML) and the server wants the client to choose explicitly.
The target resource has been assigned a new permanent URI and any future references to this resource should use the returned Location URI. Search engines will update their index.
Common Use Cases: Used when a page or API endpoint has permanently moved to a new URL. Essential for SEO when restructuring a website, changing domain names, or deprecating old URL patterns.
GET /old-page HTTP/1.1
Host: www.example.comHTTP/1.1 301 Moved Permanently
Location: https://www.example.com/new-page
Content-Type: text/html
<html><body>This page has moved to <a href="https://www.example.com/new-page">/new-page</a>.</body></html>The target resource resides temporarily under a different URI. Since the redirection might be altered on occasion, the client should continue to use the original URI for future requests.
Common Use Cases: Used for temporary redirects, such as redirecting to a login page, sending users to a maintenance page, or A/B testing different page versions.
GET /dashboard HTTP/1.1
Host: www.example.comHTTP/1.1 302 Found
Location: https://www.example.com/login?redirect=/dashboardThe server is redirecting the user agent to a different resource using a GET request, typically after a POST operation. This ensures the client does not re-submit the form data.
Common Use Cases: Used after a POST form submission to redirect to a confirmation page (the Post/Redirect/Get pattern), preventing duplicate form submissions when the user refreshes the page.
The resource has not been modified since the version specified by the request headers If-Modified-Since or If-None-Match. The server does not need to send the resource body again.
Common Use Cases: Returned when a client makes a conditional request and the resource has not changed, allowing the client to use its cached copy. This saves bandwidth and improves load times.
GET /api/users/42 HTTP/1.1
Host: api.example.com
If-None-Match: "etag-abc123"HTTP/1.1 304 Not Modified
ETag: "etag-abc123"
Cache-Control: max-age=3600The target resource resides temporarily under a different URI and the user agent must not change the request method when following the redirect. Unlike 302, the method and body are guaranteed to remain the same.
Common Use Cases: Used when you need a temporary redirect that strictly preserves the HTTP method. For example, redirecting a POST request to another endpoint without changing it to a GET.
The target resource has been assigned a new permanent URI. Like 301, but the request method and body must not change when the redirect is followed.
Common Use Cases: Used for permanent redirects when you need to preserve the HTTP method. For example, permanently redirecting a POST endpoint while ensuring clients keep sending POST requests.
29 status codes
The server cannot or will not process the request due to something that is perceived to be a client error, such as malformed request syntax, invalid request framing, or deceptive request routing.
Common Use Cases: Returned when the request body is malformed JSON, required fields are missing, query parameters are invalid, or the request otherwise does not conform to the expected format.
POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
"name": "",
"email": "not-an-email"
}HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "validation_error",
"message": "Request validation failed",
"details": [
{ "field": "name", "message": "Name is required" },
{ "field": "email", "message": "Must be a valid email address" }
]
}The request has not been applied because it lacks valid authentication credentials for the target resource. The response must include a WWW-Authenticate header indicating the applicable authentication scheme.
Common Use Cases: Returned when a request is missing authentication credentials or the provided token/credentials are expired or invalid. The client needs to authenticate before retrying.
GET /api/users/me HTTP/1.1
Host: api.example.comHTTP/1.1 401 Unauthorized
Content-Type: application/json
WWW-Authenticate: Bearer
{
"error": "unauthorized",
"message": "Authentication required. Please provide a valid Bearer token."
}Reserved for future use. Originally intended for digital payment schemes, this status code is not widely standardized but is sometimes used by APIs to indicate payment is required.
Common Use Cases: While officially reserved, some APIs use this to indicate a paid feature or subscription is required, or that the user has exceeded their free tier usage limits.
The server understood the request but refuses to authorize it. Unlike 401, authentication will not help. The client does not have the necessary permissions for the resource.
Common Use Cases: Returned when the user is authenticated but does not have the required permissions. For example, a regular user trying to access an admin-only endpoint, or accessing a resource owned by another user.
DELETE /api/users/99 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error": "forbidden",
"message": "You do not have permission to delete this user. Admin role required."
}The origin server did not find a current representation for the target resource or is not willing to disclose that one exists. This may be temporary or permanent.
Common Use Cases: The most commonly encountered error. Returned when the requested resource does not exist, such as requesting a user by an ID that is not in the database, or hitting a URL with no matching route.
GET /api/users/99999 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error": "not_found",
"message": "User with ID 99999 was not found"
}The method received in the request line is known by the origin server but not supported by the target resource. The response must include an Allow header listing the valid methods.
Common Use Cases: Returned when the HTTP method is not supported for the endpoint. For example, sending a DELETE request to a read-only resource, or a POST to an endpoint that only supports GET.
DELETE /api/reports/monthly HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...HTTP/1.1 405 Method Not Allowed
Content-Type: application/json
Allow: GET, HEAD
{
"error": "method_not_allowed",
"message": "DELETE is not allowed on this resource. Allowed methods: GET, HEAD"
}The target resource does not have a representation that would be acceptable to the user agent, according to the proactive content negotiation headers received in the request.
Common Use Cases: Returned when the server cannot produce a response matching the Accept headers sent by the client. For example, a client requests XML but the API only supports JSON.
Similar to 401, but the client needs to authenticate itself with the proxy. The proxy must return a Proxy-Authenticate header with the applicable challenge.
Common Use Cases: Returned by a proxy server when the client has not provided valid credentials for the proxy itself. Common in corporate network environments where outbound traffic goes through an authenticated proxy.
The server did not receive a complete request message within the time that it was prepared to wait. The client may repeat the request without modifications at any later time.
Common Use Cases: Returned when the client takes too long to send the full request. Can occur with slow connections, large uploads over unreliable networks, or when a client opens a connection but does not send data.
The request could not be completed due to a conflict with the current state of the target resource. The client should be able to resolve the conflict and resubmit the request.
Common Use Cases: Used when a request conflicts with existing data, such as creating a user with an email that already exists, or trying to update a resource that has been modified by another request since it was last fetched.
POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
"name": "Jane Doe",
"email": "jane@example.com"
}HTTP/1.1 409 Conflict
Content-Type: application/json
{
"error": "conflict",
"message": "A user with email jane@example.com already exists",
"existing_id": 42
}The target resource is no longer available at the origin server and this condition is likely to be permanent. Unlike 404, this explicitly indicates the resource once existed but has been intentionally removed.
Common Use Cases: Used when a resource has been deliberately and permanently deleted. Signals to search engines that they should remove the URL from their index, unlike 404 which may be temporary.
The server refuses to accept the request without a defined Content-Length header. The client may repeat the request if a valid Content-Length header is added.
Common Use Cases: Returned when the server requires the Content-Length header to be present in the request, typically for uploads or POST requests where the server needs to know the payload size in advance.
One or more conditions given in the request header fields evaluated to false when tested on the server. Used with conditional requests such as If-Match or If-Unmodified-Since.
Common Use Cases: Returned when a conditional update fails because the resource has been modified since the client last fetched it. Used to implement optimistic concurrency control in APIs.
The server is refusing to process a request because the request payload is larger than the server is willing or able to process. The server may close the connection or return a Retry-After header.
Common Use Cases: Returned when a file upload or request body exceeds the server's configured maximum size limit, such as uploading a 100MB file to an endpoint with a 10MB limit.
The server is refusing to service the request because the request-target is longer than the server is willing to interpret. This can occur when a GET request has excessively long query parameters.
Common Use Cases: Returned when the URL exceeds the server's maximum length. This often happens when too much data is encoded in query parameters instead of being sent in a POST request body.
The origin server is refusing to service the request because the payload is in a format not supported by this method on the target resource. The Content-Type or Content-Encoding is not acceptable.
Common Use Cases: Returned when the server does not support the Content-Type sent in the request. For example, sending form-urlencoded data to an endpoint that only accepts application/json.
The set of ranges in the request's Range header field has been rejected because none of the requested ranges are satisfiable for the selected representation.
Common Use Cases: Returned when a client requests a byte range that falls outside the size of the resource, such as requesting bytes 1000-2000 of a 500-byte file.
The expectation given in the request's Expect header field could not be met by at least one of the inbound servers.
Common Use Cases: Returned when the server cannot meet the requirements specified in the Expect header. Most commonly related to the Expect: 100-continue mechanism when the server rejects the request before the body is sent.
Any attempt to brew coffee with a teapot should result in this error code. This was defined in the Hyper Text Coffee Pot Control Protocol as an April Fools' joke but has been preserved as a cultural touchstone.
Common Use Cases: An Easter egg status code from an April Fools' RFC. Sometimes used humorously in APIs as a fun response, or as a deliberate refusal to process a request that the server considers absurd.
The request was directed at a server that is not able to produce a response. This can occur when a server is not configured to produce responses for the combination of scheme and authority in the request URI.
Common Use Cases: Can occur in HTTP/2 when a connection is reused for a different hostname that the server cannot handle. The client should retry the request on a different connection.
The server understands the content type and the syntax of the request is correct, but it was unable to process the contained instructions. The request is well-formed but semantically invalid.
Common Use Cases: Used when the request body is syntactically valid JSON but fails business logic validation. For example, trying to set a negative price, scheduling a meeting in the past, or providing an end date before a start date.
POST /api/events HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
"title": "Team Meeting",
"start_date": "2025-12-01",
"end_date": "2025-11-01"
}HTTP/1.1 422 Unprocessable Content
Content-Type: application/json
{
"error": "unprocessable_entity",
"message": "Semantic validation failed",
"details": [
{ "field": "end_date", "message": "End date must be after start date" }
]
}The source or destination resource of a method is locked. The client should try again later or request an unlock.
Common Use Cases: Used in WebDAV when a resource is locked by another user or process. Can also be used in APIs to indicate a resource is temporarily locked for editing by another user.
The method could not be performed on the resource because the requested action depended on another action that failed.
Common Use Cases: Used in WebDAV when an operation fails because a prerequisite operation it depends on also failed. For example, a COPY of a directory fails because copying one of the child files failed.
The server is unwilling to risk processing a request that might be replayed, to avoid potential replay attacks when using TLS 1.3 early data (0-RTT).
Common Use Cases: Used when a request arrives in TLS 1.3 early data (0-RTT) and the server cannot guarantee it has not already been processed. Prevents replay attacks on non-idempotent requests.
The server refuses to perform the request using the current protocol but might be willing to do so after the client upgrades to a different protocol. The server must include an Upgrade header indicating the required protocol.
Common Use Cases: Used when the server requires the client to switch to a newer protocol version, such as upgrading from HTTP/1.1 to HTTP/2, or from an unencrypted connection to TLS.
The origin server requires the request to be conditional. This is intended to prevent the "lost update" problem where a client GETs a resource, modifies it, and PUTs it back while another client has also modified it.
Common Use Cases: Returned when the server requires conditional headers like If-Match or If-Unmodified-Since to prevent concurrent modification issues. Forces clients to implement optimistic locking.
The user has sent too many requests in a given amount of time (rate limiting). The response should include a Retry-After header indicating how long to wait before making a new request.
Common Use Cases: Returned when the client exceeds the API rate limit. Most APIs use this to protect against abuse and ensure fair usage. Clients should back off and retry after the time specified in the Retry-After header.
GET /api/search?q=test HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1735689600
{
"error": "rate_limit_exceeded",
"message": "Rate limit exceeded. Maximum 100 requests per minute.",
"retry_after": 60
}The server is unwilling to process the request because its header fields are too large. The request may be resubmitted after reducing the size of the request header fields.
Common Use Cases: Returned when request headers exceed the server's size limits. This commonly happens when cookies grow too large, or when too much data is passed in custom headers or an oversized Authorization token.
The server is denying access to the resource as a consequence of a legal demand. The response should include an explanation of the legal restriction in the body and a Link header to identify the legal authority.
Common Use Cases: Used when a resource is blocked due to legal requirements such as government censorship orders, DMCA takedown notices, court orders, or sanctions compliance. The code number references Fahrenheit 451.
11 status codes
The server encountered an unexpected condition that prevented it from fulfilling the request. This is a generic catch-all error when no more specific 5xx status code is appropriate.
Common Use Cases: The most common server error. Returned when the server encounters an unhandled exception, a bug, a database connection failure, or any other unexpected issue during request processing.
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
{
"error": "internal_server_error",
"message": "An unexpected error occurred. Please try again later.",
"request_id": "req_abc123xyz"
}The server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it.
Common Use Cases: Returned when the server does not recognize or has not yet implemented the requested HTTP method. Can be used as a placeholder for API endpoints that are planned but not yet built.
The server, while acting as a gateway or proxy, received an invalid response from an upstream server it accessed in attempting to fulfill the request.
Common Use Cases: Returned by reverse proxies, load balancers, or API gateways when the upstream application server sends a malformed response, crashes, or is unreachable. Common during deployments.
HTTP/1.1 502 Bad Gateway
Content-Type: application/json
{
"error": "bad_gateway",
"message": "The upstream server returned an invalid response. Please try again shortly."
}The server is currently unable to handle the request due to temporary overloading or scheduled maintenance. The implication is that this is a temporary condition and the server will be available again soon.
Common Use Cases: Returned during planned maintenance windows, when the server is overloaded, or when a critical dependency is down. The Retry-After header can indicate when the client should try again.
HTTP/1.1 503 Service Unavailable
Content-Type: application/json
Retry-After: 300
{
"error": "service_unavailable",
"message": "Service is temporarily unavailable for scheduled maintenance. Expected back at 2025-12-01T03:00:00Z.",
"retry_after": 300
}The server, while acting as a gateway or proxy, did not receive a timely response from an upstream server it needed to access in order to complete the request.
Common Use Cases: Returned by reverse proxies or load balancers when the upstream application server takes too long to respond. Often indicates a slow database query, an external API timeout, or an overloaded backend.
The server does not support, or refuses to support, the major version of HTTP that was used in the request message.
Common Use Cases: Returned when the server does not support the HTTP protocol version used in the request, such as a server that only supports HTTP/1.1 receiving an HTTP/2 request it cannot handle.
The server has an internal configuration error: the chosen variant resource is configured to engage in transparent content negotiation itself, resulting in a circular reference.
Common Use Cases: A rare error indicating a misconfiguration in content negotiation on the server side, where the negotiated resource itself tries to negotiate, creating an infinite loop.
The method could not be performed on the resource because the server is unable to store the representation needed to successfully complete the request.
Common Use Cases: A WebDAV status returned when the server runs out of disk space or storage quota while trying to write data. Can also apply to APIs where a storage limit has been reached.
The server terminated an operation because it encountered an infinite loop while processing a request with "Depth: infinity". This is a more specific version of 500.
Common Use Cases: A WebDAV status returned when the server detects a circular dependency or infinite loop in resource bindings, such as a directory structure that references itself.
The policy for accessing the resource has not been met in the request. The server should send back all the information necessary for the client to issue an extended request.
Common Use Cases: A rarely used status code indicating that further extensions to the request are required for the server to fulfill it. Defined in the HTTP Extension Framework specification.
The client needs to authenticate to gain network access. This is not about HTTP-level authentication but about network-level access, such as logging in to a captive portal.
Common Use Cases: Returned by captive portals (e.g., hotel or airport Wi-Fi login pages) when the user has not yet authenticated with the network. The response body typically contains a login page.
Common HTTP headers explained with syntax, examples, and common values.
BrowseComplete guide to HTTP request methods with comparison tables and examples.
BrowseComplete reference of common MIME types with file extensions, categories, and usage examples.
BrowseComplete guide to Cross-Origin Resource Sharing — how it works, every header explained, and common errors with fixes.
Browse