HTTP Status Code
HTTP status codes act as a common language between servers and clients. An HTTP status code is a three-digit numeric response code sent by a web server to a browser or client application in response to an HTTP request. It's essentially a signal that communicates the outcome of the request.
Why HTTP status codes are important:
Clarity and Universality: These codes provide a standardized way for servers to communicate the success or failure of a request. This universal language ensures everyone (browsers, developers, applications) understands the outcome.
Troubleshooting: Status codes are crucial for troubleshooting issues between clients and servers. By understanding the code, developers can pinpoint where the problem lies (client-side error, server-side error, etc.) and take corrective actions. For example, a "404 Not Found" status code indicates that the requested resource does not exist, while a "500 Internal Server Error" indicates a problem on the server side. This helps developers diagnose and troubleshoot issues efficiently.
Improved User Experience: For user-facing applications (web apps), proper use of status codes can enhance the user experience. For instance, a 404 Not Found code can be used to display a user-friendly "Page Not Found" message, rather than a cryptic error message.
API Design: While developing REST APIs, using HTTP status codes effectively is essential. They convey the result of API calls clearly, allowing developers integrating with the API to understand what's happening.
SEO and Web Standards: Proper use of status codes can impact search engine optimization (SEO) and adherence to web standards. For example, returning the appropriate status code for redirects (e.g., "301 Moved Permanently") ensures that search engines understand the change in URL and transfer any link equity.
HTTP Status Codes and use case
Below are some of the common HTTP status codes and their typical uses in REST APIs
1xx Informational: These codes indicate the request was received and the process is ongoing. They don't necessarily mean success, but rather the server is working on it.
100 Continue: The client can continue with its request.
101 Switching Protocols: The server switches protocols as requested by the client.
2xx Success: These are the happy path codes, indicating the request was successfully processed and understood.
200 OK: The request was successful. Example: When a client sends a GET request for a webpage, and the server successfully retrieves and returns the webpage content, it responds with a 200 status code.
201 Created: The request has been fulfilled and a new resource has been created. Example: When a client sends a POST request to create a new user account, and the server successfully creates the account, it responds with a 201 status code along with the URI of the newly created user resource.
202 Accepted: This status code indicates that the request has been accepted for processing but has not yet been completed. It is typically used in scenarios where the request is queued for asynchronous processing. Example: When a server receives a request to process a large batch job, it might respond with a 202 status code to acknowledge receipt of the request, while the actual processing happens asynchronously.
203 Non-Authoritative Information: This status code indicates that the server is returning a meta-information response (such as headers) that may be from a third-party source rather than the original server. It is primarily used in proxy scenarios. Example: A proxy server may return a 203 status code along with cached content from another server, indicating to the client that the information provided is not authoritative
204 No Content: The server successfully processed the request but isn't returning any content. Example: When a client sends a PUT request to update a resource, and the server successfully updates the resource without returning any additional data, it responds with a 204 status code.
205 Reset Content: This status code instructs the client to reset the document from which the original request was sent. It is primarily used in scenarios where the client-side form data should be cleared after a successful submission. Example: After submitting a form to update some data, the server might respond with a 205 status code, prompting the client to clear the form fields to prevent accidental resubmission.
206 Partial Content: This status code is used when the server is delivering only a partial response to the client, typically in response to a request with a Range header. Example: When a client requests a large file and specifies a range of bytes it needs (e.g., for resuming a paused download), the server may respond with a 206 status code and send only the requested range of bytes.
3xx Redirection: These codes indicate the client needs to take further action to complete the request, typically involving redirection to a different URL.
300 Multiple Choices: This status code indicates that the requested resource has multiple representations available, each with its own specific location, and the user or user agent can select from among them. Example: A client requests a document that exists in multiple formats (e.g., HTML, PDF, TXT), and the server responds with a 300 status code along with a list of available representations.
301 Moved Permanently: The resource requested has been permanently moved to a new URL. This status code indicates that the resource requested has been permanently moved to a new URL. The new URL should be provided in the response. Example: When a client requests a webpage that has been moved to a new domain or location, the server responds with a 301 status code and provides the new URL for the client to access.
302 Found: When a resource temporarily resides at a different URL, the server might respond with a 302 status code and provide the temporary URL. Example: When a resource temporarily resides at a different URL, the server might respond with a 302 status code and provide the temporary URL.
303 See Other: This status code indicates that the response to the request can be found at a different URI and should be retrieved using a GET method on that resource. Example: After processing a POST request (e.g., form submission), the server may respond with a 303 status code along with the URI of a resource that the client should retrieve using a GET request.
304 Not Modified: This status code is used for caching purposes. It indicates that the requested resource hasn't changed since the client last accessed it, and the client can use its cached copy. Example: When a client sends a conditional GET request for a resource, and the server determines that the resource hasn't been modified since the last request, it responds with a 304 status code, instructing the client to use its cached copy.
305 Use Proxy: This status code is rarely used and is defined in the HTTP/1.1 specification. It indicates that the requested resource must be accessed through the proxy specified in the Location header. Example: If a client's request can only be fulfilled by using a proxy, the server may respond with a 305 status code, instructing the client to access the resource via the specified proxy.
307 Temporary Redirect: This status code indicates that the requested resource has been temporarily moved to a different URL. The client should issue the same request to the new URL. Example: Similar to 301, but indicating a temporary move rather than a permanent one. It's particularly useful for preserving the original request method and body during redirection.
4xx Client Error: These codes indicate an issue with the request itself, typically due to a mistake on the client-side (e.g., browser, your application).
400 Bad Request: This status code indicates that the server cannot process the request due to invalid syntax or other client-side errors. Example: When a client sends a request with missing parameters or malformed data, the server responds with a 400 status code to indicate the bad request.
401 Unauthorized: This status code indicates that the request requires authentication. The client must provide valid credentials to access the resource. Example: When a client attempts to access a protected resource without providing authentication credentials, the server responds with a 401 status code, prompting the client to authenticate.
402 Payment Required: This status code is reserved for future use and is not currently implemented in most servers. It was originally intended to be used for online payment processing.
403 Forbidden: This status code indicates that the server understood the request but refuses to authorize it. The client does not have permission to access the requested resource. Example: When a client attempts to access a resource for which they do not have the necessary permissions, the server responds with a 403 status code, denying access.
404 Not Found: It indicates that the server cannot find the requested resource. Essentially, the server has searched for the resource but couldn't locate it. Example: When a user tries to access a webpage that doesn't exist on a website, the server responds with a 404 status code, indicating that the page is not found.
405 Method Not Allowed: This status code indicates that the method used in the request (such as GET, POST, PUT, DELETE, etc.) is not supported for the requested resource. Example: If a client sends a PUT request to a resource that only allows GET requests, the server would respond with a 405 status code, indicating that the method used is not allowed.
406 Not Acceptable: This status code indicates that the server cannot generate a response that is acceptable according to the Accept headers sent in the request. Example: If a client requests data in a format that the server cannot provide, the server would respond with a 406 status code, indicating that it cannot fulfill the request with the desired content type.
407 Proxy Authentication Required: This status code is similar to 401 (Unauthorized), but it indicates that the client must first authenticate itself with the proxy. Example: When a client tries to access a resource through a proxy server that requires authentication, the proxy server would respond with a 407 status code, prompting the client to provide proper authentication credentials.
408 Request Time-out: This status code indicates that the server did not receive a complete request from the client within the server's specified timeout period. Example: If a client takes too long to send data to the server, the server might close the connection and respond with a 408 status code, indicating that the request has timed out.
409 Conflict: This status code indicates that the request could not be completed due to a conflict with the current state of the target resource. Example: If a client attempts to update a resource but the server detects a conflict with another change that has been made since the client last retrieved the resource, the server would respond with a 409 status code, indicating a conflict.
410 Gone: This status code indicates that the requested resource is no longer available, and the server does not have a forwarding address. Example: When a resource that was previously available on a website has been intentionally removed and will not be returning, the server would respond with a 410 status code, indicating that the resource is gone permanently.
411 Length Required: This status code indicates that the server refuses to accept the request without a defined Content-Length header. Example: If a client sends a request that requires a body (e.g., a POST request) but does not include a Content-Length header specifying the size of the body, the server would respond with a 411 status code, indicating that the length of the content is required.
412 Precondition Failed: This status code indicates that one or more conditions specified in the request headers evaluated to false when tested on the server. Example: If a client sends a conditional request (e.g., with an If-Match or If-None-Match header) and the conditions specified are not met, the server would respond with a 412 status code, indicating that the precondition failed.
413 Request Entity Too Large: This status code indicates that the server refuses to process the request because the payload is larger than the server is willing or able to process. Example: If a client sends a request with a body that exceeds the server's specified size limits, the server would respond with a 413 status code, indicating that the payload is too large.
414 Request-URI Too Large: This status code indicates that the URI (Uniform Resource Identifier) provided in the request is too long for the server to process. Example: If a client sends a request with a URI that exceeds the server's specified length limits, the server would respond with a 414 status code, indicating that the URI is too long.
415 Unsupported Media Type: This status code indicates that the server refuses to accept the request because the payload format is in an unsupported format. Example: If a client sends a request with a Content-Type header that the server does not support, the server would respond with a 415 status code, indicating that the media type is not supported.
416 Requested range not satisfiable: This status code indicates that the server cannot fulfill the partial GET request because the client has requested a portion of the resource that cannot be supplied. Example: If a client sends a Range header in a GET request, specifying a range of bytes that is not valid for the resource, the server would respond with a 416 status code, indicating that the range is not satisfiable.
417 Expectation Failed: This status code indicates that the server cannot meet the requirements of the Expect request-header field. Example: If a client sends an Expect header with expectations that the server cannot meet, the server would respond with a 417 status code, indicating that the expectation failed.
5xx Server Error: These codes indicate an issue on the server-side preventing it from fulfilling the request.
500 Internal Server Error: This status code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request. Example: If there is an error in the server-side code, database connection issue, or any other unforeseen problem, the server would respond with a 500 status code, indicating an internal server error.
501 Not Implemented: This status code indicates that the server does not support the functionality required to fulfill the request. Example: If a client sends a request for a feature that the server does not support or has not implemented, the server would respond with a 501 status code, indicating that the functionality is not implemented.
502 Bad Gateway: This status code indicates that the server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request. Example: If a proxy server receives an invalid response from the upstream server when trying to fulfill a client request, the proxy server would respond with a 502 status code, indicating a bad gateway.
503 Service Unavailable: This status code indicates that the server is currently unable to handle the request due to temporary overloading or maintenance of the server. Example: If a server is overloaded with requests or undergoing maintenance, it might respond with a 503 status code, indicating that the service is temporarily unavailable.
504 Gateway Timeout: This status code indicates that the server, while acting as a gateway or proxy, did not receive a timely response from the upstream server it accessed in attempting to complete the request. Example: If a proxy server does not receive a response from the upstream server within a specified timeout period, it would respond with a 504 status code, indicating a gateway timeout.
505 HTTP Version not supported: This status code indicates that the server does not support the HTTP protocol version used in the request. Example: If a client sends a request using an HTTP version that the server does not support (e.g., HTTP/2.0 when the server only supports HTTP/1.1), the server would respond with a 505 status code, indicating that the HTTP version is not supported.
Correlation of HTTP status codes with HTTP methods (verbs)
HTTP Method (Verb)
HTTP Method (Verb) | Typical Use Case | Common Status Codes |
GET | Retrieve data from a resource | * 200 OK: Success, data returned in response body. * 301 Moved Permanently: Resource has been moved to a new location. * 401 Unauthorized: Client lacks proper credentials. * 403 Forbidden: Client authorized but not allowed to access resource. * 404 Not Found: Requested resource could not be found. |
POST | Create a new resource | * 201 Created: New resource created successfully, location of new resource in response (e.g., in a header). * 400 Bad Request: Invalid data provided in the request body. * 401 Unauthorized: Client lacks proper credentials. * 403 Forbidden: Client not authorized to create new resources. * 409 Conflict: Resource creation conflicts with existing data. |
PUT | Update a complete resource | * 200 OK: Resource updated successfully. * 204 No Content: Resource updated but no data returned in response body. * 400 Bad Request: Invalid data provided in the request body. * 401 Unauthorized: Client lacks proper credentials. * 403 Forbidden: Client not authorized to update resource. * 404 Not Found: Resource could not be found for update. |
PATCH | Update a partial resource | * 200 OK: Resource partially updated successfully. * 204 No Content: Resource updated but no data returned in response body. * 400 Bad Request: Invalid data provided in the request body. * 401 Unauthorized: Client lacks proper credentials. * 403 Forbidden: Client not authorized to update resource. * 404 Not Found: Resource could not be found for update. |
DELETE | Delete a resource | * 200 OK: Resource deleted successfully (may or may not have content in response body). * 204 No Content: Resource deleted successfully, no content returned. * 401 Unauthorized: Client lacks proper credentials. * 403 Forbidden: Client not authorized to delete resource. * 404 Not Found: Resource could not be found for deletion. |
Last updated