HTTP status code

The HTTP 426 status code stands for "Upgrade Required". It is a client error response indicating that the client must upgrade to a different version of the protocol in order to complete the request. This status code is used when the server requires the client to use a more recent version of a protocol (such as HTTP/2, HTTP/3, or a specific API version) than the one currently being used.

When is HTTP 426 Used?

• The 426 Upgrade Required status code is typically returned when the client is attempting to use an older or incompatible version of the protocol (like HTTP/1.1), and the server requires a newer version to proceed.
• It can also be used in APIs or other systems where certain features or operations are only supported in later versions, and the client needs to upgrade to take advantage of those features.

Common Causes of HTTP 426 Errors

• Outdated HTTP version: The client is using an older version of HTTP (such as HTTP/1.1), but the server requires a more recent version, such as HTTP/2 or HTTP/3.
• Deprecated API version: The client is using an outdated version of an API, and the server requires the client to switch to a newer version of the API to ensure compatibility and access to newer features.
• Required protocol features: The client is trying to access resources or perform actions that depend on features only available in a later version of the protocol.

Example Scenarios

• A client attempts to access a server that only supports HTTP/2, but the client is using HTTP/1.1. The server responds with a 426 error, requiring the client to upgrade to HTTP/2.
• A user tries to use an API that has deprecated support for an old version, and the server responds with a 426 status code, prompting the user to upgrade to the latest version of the API.

Example

Client Request (Old HTTP Version)

    
        GET / HTTP/1.1
        Host: example.com
    

(The client sends a request using HTTP/1.1, but the server requires HTTP/2.)

Server Response (426 Upgrade Required)

    
        HTTP/1.1 426 Upgrade Required
        Content-Type: application/json
        Upgrade: h2c

        {
          "error": "Please upgrade to HTTP/2 to access this resource."
        }
    

Best Practices for Handling HTTP 426

• Provide upgrade instructions: When returning a 426 response, the server should specify which protocol version or API version the client should upgrade to, and ideally provide links to resources or documentation.
• Graceful fallback: If applicable, the server can offer the client a fallback or alternate path that works with the older protocol version, though upgrading should be the preferred route.
• Client-side awareness: Clients should be aware of the protocol versions they are using and ensure they support the required versions. For example, browsers can automatically switch to newer versions of HTTP like HTTP/2 when supported by the server.
• API version management: If the error is related to an API version, the server should communicate which version of the API is required and encourage the client to update to the latest version.

Summary

HTTP 426 is used when the client must upgrade to a newer version of the protocol (e.g., HTTP/2 or HTTP/3) in order to complete the request. It can also be used when a client is accessing an outdated version of an API or system that requires an upgrade. The server should specify what upgrade is needed and provide guidance for the client to follow.