The Ultimate Reference for HTTP Status Codes in API Design

In the world of web development and API design, HTTP status codes play a crucial role in communicating the outcome of requests between clients and servers. These codes provide a standardized way to indicate specific conditions, successes, or errors that occur during the processing of HTTP requests. Understanding these status codes is essential for developers, as it helps in debugging, error handling, and creating more robust applications.

1. 1xx Informational

These status codes indicate a provisional response. They are rarely used in practice but can be helpful in certain scenarios.

• 100 Continue: The server has received the request headers and the client should proceed to send the request body.
• 101 Switching Protocols: The requester has asked the server to switch protocols and the server has agreed to do so.

2. 2xx Success

These status codes indicate that the client's request was successfully received, understood, and accepted.

• 200 OK: The request was successful, and the response contains the requested data or result.
  • Example: Retrieving a user's profile information.
• 201 Created: The request was successful, and a new resource was created.
  • Example: Creating a new user account or posting a new blog entry.
• 204 No Content: The server successfully processed the request but is not returning any content.
  • Example: Updating a user's settings where no response body is needed.
• 206 Partial Content: The server is delivering only part of the resource due to a range header sent by the client.
  • Example: Streaming video content or downloading large files in chunks.

3. 3xx Redirection

These status codes indicate that further action needs to be taken by the user agent to fulfill the request.

• 301 Moved Permanently: The requested resource has been permanently moved to a new URL.
• 302 Found: The requested resource resides temporarily under a different URL.
• 304 Not Modified: Indicates that the resource has not been modified since the version specified by the request headers.

4. 4xx Client Error

These status codes are intended for situations in which the client seems to have erred.

• 400 Bad Request: The server cannot process the request due to invalid syntax or bad input.

  • Example: Sending malformed JSON in the request body.
  • Usage: Use when the request itself is malformed or contains invalid parameters.

• 401 Unauthorized: The request requires user authentication.

  • Example: Attempting to access a protected API endpoint without providing valid credentials.
  • Usage: Use when authentication is required and has not been provided or is invalid.

• 403 Forbidden: The server understands the request but refuses to authorize it.

  • Example: A user trying to access admin-only features.
  • Usage: Use when the user is authenticated but does not have permission for the requested operation.

• 404 Not Found: The requested resource could not be found on the server.

  • Example: Attempting to retrieve a deleted user profile.
  • Usage: Use when the requested resource does not exist.

• 405 Method Not Allowed: The method specified in the request is not allowed for the resource identified by the request URI.

  • Example: Sending a POST request to an endpoint that only accepts GET requests.

• 409 Conflict: The request could not be processed because of a conflict with the current state of the resource.

  • Example: Trying to create a user with an email that already exists in the system.
  • Usage: Use when there is a conflict with the current state of the resource, such as duplicate entries.

• 422 Unprocessable Entity: The server understands the content type and syntax of the request, but cannot process the contained instructions.

  • Example: Submitting a form with invalid data that fails server-side validation.
  • Usage: Use for validation errors where the request syntax is correct, but the data is semantically incorrect.

• 429 Too Many Requests: The user has sent too many requests in a given amount of time ("rate limiting").

  • Example: Implementing API rate limiting to prevent abuse.

5. 5xx Server Error

These status codes indicate cases in which the server is aware that it has encountered an error or is otherwise incapable of performing the request.

• 500 Internal Server Error: A generic error message indicating that the server encountered an unexpected condition that prevented it from fulfilling the request.

  • Example: An unhandled exception occurs in the server-side code.

• 501 Not Implemented: The server does not support the functionality required to fulfill the request.

  • Example: Using a new HTTP method that the server doesn't recognize.

• 502 Bad Gateway: The server, while acting as a gateway or proxy, received an invalid response from the upstream server.

  • Example: A reverse proxy server cannot connect to the origin server.

• 503 Service Unavailable: The server is currently unable to handle the request due to temporary overloading or maintenance.

  • Example: A server is undergoing scheduled maintenance or experiencing high traffic.

• 504 Gateway Timeout: The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server.

  • Example: A timeout occurs while waiting for a response from a third-party API.

Best Practices for Using HTTP Status Codes

1. Be Specific: Use the most specific status code that applies to the situation. This helps clients understand exactly what happened and how to respond.

2. Consistent Usage: Maintain consistency in how you use status codes across your API. This makes it easier for developers to work with your API.

3. Provide Additional Information: Along with the status code, include a detailed error message in the response body when appropriate. This can help with debugging and improve the developer experience.

4. Security Considerations: Be cautious about revealing too much information in error responses, especially for 4xx and 5xx errors. Avoid exposing sensitive details about your system architecture or implementation.

5. Documentation: Clearly document which status codes your API uses and under what circumstances. This helps API consumers understand how to interpret and handle different responses.

By understanding and properly implementing HTTP status codes, developers can create more robust, clear, and user-friendly APIs and web applications. These codes serve as a crucial communication tool between clients and servers, helping to streamline error handling and improve overall system reliability.