HTTP Status Codes Reference
1xx Informational
Continue
The server has received the request headers and the client should proceed to send the request body.
When to use: When sending a large request body and the client wants to check if the server will accept it before transmitting.
Switching Protocols
The server is switching protocols as requested by the client via the Upgrade header.
When to use: When upgrading from HTTP to WebSocket or to a newer version of HTTP.
Processing
The server has received and is processing the request, but no response is available yet.
When to use: For long-running WebDAV requests to prevent the client from timing out.
Early Hints
Used to return some response headers before the final HTTP message, allowing the browser to preload resources.
When to use: To hint the browser to preload CSS, fonts, or scripts while the server prepares the full response.
2xx Success
OK
The request has succeeded. The meaning depends on the HTTP method used.
When to use: For successful GET, PUT, PATCH, or DELETE requests that return data or confirmation.
Created
The request has been fulfilled and a new resource has been created.
When to use: After a successful POST request that creates a new resource. Include a Location header pointing to the new resource.
Accepted
The request has been accepted for processing, but the processing has not been completed.
When to use: For asynchronous operations where the server queues work for later processing (e.g., batch jobs, email sending).
No Content
The server has successfully fulfilled the request and there is no additional content to send.
When to use: After a successful DELETE request or a PUT/PATCH that does not need to return the updated resource.
Partial Content
The server is delivering only part of the resource due to a Range header sent by the client.
When to use: When serving large files with resume support, video streaming, or paginated downloads.
Multi-Status
Conveys information about multiple resources in situations where multiple status codes might be appropriate.
When to use: In WebDAV operations that affect multiple resources, where each sub-request may have a different status.
3xx Redirection
Moved Permanently
The resource has been permanently moved to a new URL. All future requests should use the new URL.
When to use: When a page or resource has permanently moved. Search engines will update their index to the new URL.
Found
The resource has been temporarily moved to a different URL. The client should continue using the original URL.
When to use: For temporary redirects such as during maintenance or A/B testing. Note: some clients change POST to GET.
See Other
The response to the request can be found at a different URL using a GET method.
When to use: After a POST request to redirect the client to a confirmation page (Post/Redirect/Get pattern).
Not Modified
The resource has not been modified since the version specified by the request headers (If-Modified-Since or If-None-Match).
When to use: For caching — when the client already has the latest version and no data transfer is needed.
Temporary Redirect
The resource has been temporarily moved to a different URL. The request method must not change.
When to use: Like 302, but guarantees the HTTP method will not change (a POST stays a POST).
Permanent Redirect
The resource has been permanently moved and the request method must not change.
When to use: Like 301, but guarantees the HTTP method will not change. Useful for API endpoints that moved.
4xx Client Error
Bad Request
The server cannot process the request due to malformed syntax, invalid parameters, or deceptive routing.
When to use: When the request body or query parameters fail validation or are malformed.
Unauthorized
The request requires user authentication. The client must provide valid credentials.
When to use: When the request lacks valid authentication credentials (no token, expired token, invalid credentials).
Forbidden
The server understood the request but refuses to authorize it. Authentication will not help.
When to use: When the user is authenticated but does not have permission to access the resource.
Not Found
The server cannot find the requested resource. The URL may be wrong or the resource may have been deleted.
When to use: When the requested resource does not exist at the given URL.
Method Not Allowed
The HTTP method used is not supported for the requested resource.
When to use: When a client sends a POST to a read-only endpoint or a DELETE to a non-deletable resource.
Not Acceptable
The server cannot produce a response matching the Accept headers sent by the client.
When to use: When content negotiation fails — the client requests a format the server cannot provide.
Request Timeout
The server timed out waiting for the client to send the complete request.
When to use: When a client takes too long to send the request body or complete the handshake.
Conflict
The request could not be completed due to a conflict with the current state of the resource.
When to use: For version conflicts, duplicate entries, or when a resource is in a state that prevents the action.
Gone
The resource is no longer available and no forwarding address is known. This is permanent.
When to use: When a resource has been intentionally and permanently removed, unlike 404 which may be temporary.
Payload Too Large
The request entity is larger than the server is willing or able to process.
When to use: When a file upload or request body exceeds the server's configured maximum size.
URI Too Long
The URI provided was too long for the server to process.
When to use: When a GET request with excessive query parameters exceeds the URL length limit.
Unsupported Media Type
The media format of the request data is not supported by the server.
When to use: When the Content-Type header specifies a format the endpoint does not accept (e.g., XML instead of JSON).
Unprocessable Entity
The server understands the content type and syntax but cannot process the contained instructions.
When to use: When the request is well-formed but has semantic errors (e.g., validation failures on business rules).
Too Many Requests
The user has sent too many requests in a given amount of time (rate limiting).
When to use: To enforce rate limits. Include a Retry-After header to indicate when the client can try again.
Unavailable For Legal Reasons
The resource is unavailable due to legal demands such as government censorship or court order.
When to use: When a resource is blocked due to legal requirements, such as GDPR takedowns or DMCA requests.
5xx Server Error
Internal Server Error
A generic error message indicating an unexpected condition on the server.
When to use: As a catch-all when the server encounters an unhandled exception or unexpected error.
Not Implemented
The server does not support the functionality required to fulfill the request.
When to use: When the server does not recognize the request method or lacks the ability to fulfill it.
Bad Gateway
The server, acting as a gateway or proxy, received an invalid response from the upstream server.
When to use: When a reverse proxy (Nginx, load balancer) cannot get a valid response from the backend server.
Service Unavailable
The server is currently unable to handle the request due to temporary overload or maintenance.
When to use: During planned maintenance or when the server is overloaded. Include a Retry-After header if possible.
Gateway Timeout
The server, acting as a gateway or proxy, did not receive a timely response from the upstream server.
When to use: When a reverse proxy times out waiting for the backend to respond.
Complete reference of all HTTP status codes with descriptions, use cases, and examples. Search and filter by category (1xx-5xx).
How to Use HTTP Status Codes Reference
- Browse the status codes grouped by category (1xx through 5xx).
- Use the search box at the top to filter codes by number, name, or description.
- Each code includes its name, a description, and guidance on when to use it.
- Color-coded badges help you quickly identify the category of each code.
What Are HTTP Status Codes?
HTTP status codes are three-digit numbers returned by a web server in response to a client's request. They indicate whether the request was successful, requires further action, or encountered an error. Status codes are part of the HTTP protocol defined in RFC 7231 and are essential for building and debugging web applications, REST APIs, and any system that communicates over HTTP. Every web developer needs to understand these codes to properly handle responses and communicate errors to users.
The Five Status Code Classes
Status codes are grouped into five classes based on their first digit. 1xx Informational codes indicate that the request has been received and processing is continuing (rarely seen in practice). 2xx Success codes mean the request was successfully received, understood, and accepted. 3xx Redirection codes indicate the client must take additional action to complete the request. 4xx Client Error codes indicate that the request contains bad syntax or cannot be fulfilled due to a client-side issue. 5xx Server Error codes mean the server failed to fulfill a valid request due to a server-side problem.
Most Important Status Codes
- 200 OK - Request succeeded (the most common response)
- 201 Created - Resource successfully created (POST requests)
- 301/302 - Permanent/temporary redirect to a new URL
- 400 Bad Request - Invalid request syntax or parameters
- 401 Unauthorized - Authentication required
- 403 Forbidden - Authenticated but not authorized
- 404 Not Found - Resource does not exist
- 429 Too Many Requests - Rate limit exceeded
- 500 Internal Server Error - Generic server failure
Status Codes in REST API Design
Choosing the right status code is a key aspect of good API design. Return 200 for successful GET requests, 201 for successful POST that creates a resource, and 204 for successful DELETE with no response body. Use 400 for validation errors with a descriptive error message in the body, 401 when the user needs to authenticate, and 403 when they are authenticated but lack permission. Return 404 when a resource is not found, and 409 for conflicts (like duplicate entries). On the server side, 500 indicates an unexpected error, while 502 and 503 point to infrastructure issues like gateway failures or service unavailability.
For debugging URLs, try the URL Parser. For network configuration, use the Subnet Calculator. For API development tools, see the JSON Validator.