HTTP status codes are integral to RESTful APIs as they convey the outcome of a client's request to the server. They are categorized into five main groups, each corresponding to different types of results: informational, success, redirection, client error, and server error. Below is an in-depth explanation of these categories and examples of how and when these status codes are used.
1. 1xx (Informational)
These codes indicate that the server has received the request and is in the process of handling it, but no final response is available yet.
100 Continue: The server has received the request headers, and the client should proceed to send the request body.
101 Switching Protocols: The server agrees to switch to a different protocol (e.g., from HTTP/1.1 to HTTP/2).
These are rarely encountered in everyday API usage since most interactions don't require intermediate informational responses.
2. 2xx (Success)
These codes indicate that the request was successfully received, understood, and processed by the server.
200 OK: The request was successful, and the server returned the requested data. This is the most common status for successful GET, PUT, or DELETE requests.
- Example: When retrieving a list of users from the API:
{
"status": "success",
"data": [
{"id": 1, "name": "John Doe"},
{"id": 2, "name": "Jane Doe"}
]
}
201 Created: The request was successful, and a new resource has been created as a result. This is typically returned for POST requests that create new resources.
Example: After creating a new user:
{ "status": "success", "data": {"id": 3, "name": "Sarah Smith", "email": "sarah@example.com"} }
204 No Content: The request was successful, but there is no content to return in the response. This is common for successful DELETE or PUT requests where no further data needs to be returned.
Example: After successfully deleting a user:
{ "status": "success", "message": "User deleted successfully" }
3. 3xx (Redirection)
These codes indicate that the client must take additional actions to complete the request, such as following a redirect to another URL.
301 Moved Permanently: The requested resource has been permanently moved to a new URL. Future requests should use the new URL.
- Example: A URL has been permanently moved to a new location:
{
"status": "redirect",
"message": "The resource has been permanently moved to /new-location"
}
302 Found: The requested resource is temporarily available at a different URL. Clients should continue using the original URL for future requests.
Example: Temporary redirection to another URL:
{ "status": "redirect", "message": "The resource is temporarily available at /temporary-location" }
303 See Other: The response to the request can be found at another URL, typically using the GET method.
- Example: Redirect after a successful POST request to a resource:
{
"status": "redirect",
"message": "Please see the newly created resource at /users/4"
}
304 Not Modified: The resource has not been modified since the last request, and no content is returned.
- Example: When checking if a resource has changed since the last request:
{
"status": "not_modified",
"message": "No changes to the resource since the last request"
}
4. 4xx (Client Error)
These codes indicate that there was an error in the request, typically due to incorrect data or authorization issues.
400 Bad Request: The request is invalid or malformed, and the server cannot understand it.
- Example: If a POST request to create a user contains missing or invalid data:
{
"status": "error",
"message": "Invalid data: 'name' field is required"
}
401 Unauthorized: The request requires authentication, but the client has not provided valid credentials.
- Example: A user tries to access a protected resource without providing an API key:
{
"status": "error",
"message": "Authentication required"
}
403 Forbidden: The client is authenticated, but they do not have permission to access the requested resource.
- Example: A user tries to delete a resource they don't have permission to:
{
"status": "error",
"message": "You do not have permission to perform this action"
}
404 Not Found: The requested resource could not be found on the server.
Example: A user tries to retrieve a resource that does not exist:
{ "status": "error", "message": "Resource not found" }
5. 5xx (Server Error)
These codes indicate that the server failed to fulfill a valid request, usually due to an error or issue on the server side.
500 Internal Server Error: The server encountered an unexpected condition that prevented it from fulfilling the request.
- Example: A server error occurred during the processing of a request:
{
"status": "error",
"message": "An unexpected error occurred on the server"
}
503 Service Unavailable: The server is temporarily unable to handle the request, typically due to overload or maintenance.
- Example: When the API service is down for maintenance:
{
"status": "error",
"message": "Service is temporarily unavailable due to maintenance"
}
Summary of Common HTTP Status Codes:
1xx (Informational): These codes indicate the request is being processed.
2xx (Success): The request was successful and the server returned a valid response (e.g., 200 OK, 201 Created).
3xx (Redirection): The client must perform additional actions (e.g., 301 Moved Permanently, 302 Found).
4xx (Client Error): The client made a bad request (e.g., 400 Bad Request, 404 Not Found).
5xx (Server Error): The server encountered an error (e.g., 500 Internal Server Error, 503 Service Unavailable).
These status codes are crucial for diagnosing issues with API requests and for providing clients with the appropriate response to guide them in taking further actions.