Detailed reference guide explaining HTTP status codes essential for web and API development.
Understanding HTTP Status Codes
HTTP status codes are standardized response codes issued by servers when receiving a request from a client. These codes provide insight into the outcome of the request, whether it succeeded, failed, or needs additional action.
The codes are categorized into five main classes, each defining a different type of response:
- 1xx (Informational): Request received and understood, continuing the process.
- 2xx (Successful): Request successfully processed.
- 3xx (Redirection): Further action necessary to complete the request.
- 4xx (Client Errors): Issues caused by invalid input/requests from the client.
- 5xx (Server Errors): Failures that occur on the server.
This guide focuses on helping developers select the most appropriate HTTP status codes for their APIs and web services.
The 200-Level Codes: Successful Requests
The 200-level status codes indicate successful processing of the request. These are the most common codes used in web and API communication.
- 200 (OK): The request has succeeded. It is the most generic success response.
- 201 (Created): Indicates that a resource has been successfully created. Often used in POST requests.
- 204 (No Content): The request has been processed successfully, but no content is returned. Frequently used for DELETE requests when no response body is needed.
Redirection Codes: The 300 Family
The 300-level status codes relate to redirection scenarios, where the client may need to perform additional actions to fully resolve the request.
- 301 (Moved Permanently): The resource has been permanently moved to a new URL.
- 302 (Found): The resource has temporarily been moved, and the client should use a different URL for now.
- 304 (Not Modified): Indicates that the resource has not changed since the last request, enabling efficient browser caching.
Client Errors: The 400-Level Codes
The 400-level status codes deal with errors originating from the client's request. These frequently occur when input is incomplete, invalid, or unauthorized.
- 400 (Bad Request): Generic error for malformed or invalid requests. For example, missing required parameters in an API call.
- 401 (Unauthorized): Authentication has failed. The request lacks valid credentials.
- 403 (Forbidden): The client is authenticated but does not have permission to access the requested resource.
- 404 (Not Found): The requested resource does not exist or cannot be found.
Server Errors: The 500-Level Codes
Server errors occur when there is a problem on the server while attempting to process the request. These errors indicate unexpected behavior or temporary server issues.
- 500 (Internal Server Error): A general error indicating that the server faced an issue it wasn’t prepared to handle.
- 503 (Service Unavailable): The server is temporarily unable to handle the request. Often used for maintenance or overloading.
Understanding the causes and proper responses for server errors helps maintain transparency with API clients, minimizing confusion in debugging issues.
FAQ
What is the difference between the 401 and 403 status codes?
A 401 (Unauthorized) error means the client is not authenticated and must provide valid credentials (e.g., API key or login details). A 403 (Forbidden) error means the client’s credentials are valid, but they lack permission to access the requested resource.
When should I use the 204 status code?
The 204 (No Content) status code is used when a request is successfully processed, but there is no content to include in the response. It's commonly used in DELETE operations in APIs when confirmation of the operation is all that's required, without returning additional data.
What does a 304 status code indicate?
A 304 (Not Modified) status code informs the client that the requested resource has not changed since the last request (based on caching headers). This allows the client to use its cached version, saving bandwidth and improving performance.
Can I use 400 for all client errors?
While you technically can use 400 (Bad Request) for any client-side error, it is better to use more specific codes like 401 (Unauthorized) for authentication-related issues or 404 (Not Found) when a resource is missing. This provides clearer communication to clients about the cause of the issue.
How should APIs handle 500 errors?
A 500 (Internal Server Error) indicates an unexpected issue on the server side. Returning this code helps distinguish server errors from client-side issues. However, avoid exposing internal server details in the response. Provide generic error messages and log detailed errors internally for later debugging.
Official reference: MDN HTTP documentation.