426 Upgrade Required
Description
The 426 Upgrade Required status code indicates that the server refuses to perform the request using the current protocol but might be willing to do so after the client upgrades to a different protocol. The server sends an Upgrade header with this response, indicating the required protocol(s).
This status code is commonly used when: - A server requires clients to use a newer version of HTTP (e.g., HTTP/2 or HTTP/3) - A server requires secure connections via HTTPS instead of HTTP - A server requires WebSocket protocol for real-time communication - A server implements a protocol transition strategy
The 426 Upgrade Required status helps servers enforce protocol requirements while providing clients with clear information about how to proceed.
Syntax
The server responds with a 426 Upgrade Required status and includes an Upgrade header:
HTTP/1.1 426 Upgrade Required
Upgrade: [required protocol]
Connection: Upgrade
Content-Type: application/json
Content-Length: [length in bytes]
{
"error": "Upgrade Required",
"message": "A protocol upgrade is required to access this resource"
}
Examples
HTTP to HTTPS Upgrade Example
A client attempts to access a resource using HTTP when HTTPS is required:
Client Request:
Server Response:
HTTP/1.1 426 Upgrade Required
Upgrade: TLS/1.2, HTTP/1.1
Connection: Upgrade
Content-Type: text/html
Content-Length: 345
<!DOCTYPE html>
<html>
<head>
<title>Upgrade Required</title>
</head>
<body>
<h1>426 Upgrade Required</h1>
<p>This resource requires secure access via HTTPS.</p>
<p>Please access this page at <a href="https://example.com/secure-area">https://example.com/secure-area</a> instead.</p>
</body>
</html>
HTTP/1.1 to HTTP/2 Upgrade Example
A client uses HTTP/1.1 for an API that requires HTTP/2:
Client Request:
GET /api/v2/data HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Server Response:
HTTP/1.1 426 Upgrade Required
Upgrade: h2c
Connection: Upgrade
Content-Type: application/json
Content-Length: 187
{
"error": "Upgrade Required",
"message": "This API version requires HTTP/2",
"documentation": "https://api.example.com/docs/protocol-requirements",
"upgrade_to": "HTTP/2"
}
WebSocket Upgrade Example
A client attempts to access a real-time service without using WebSocket:
Client Request:
Server Response:
HTTP/1.1 426 Upgrade Required
Upgrade: websocket
Connection: Upgrade
Content-Type: application/json
Content-Length: 215
{
"error": "Upgrade Required",
"message": "This endpoint requires the WebSocket protocol",
"websocket_url": "wss://live.example.com/real-time-updates",
"documentation": "https://live.example.com/docs/websocket"
}
Summary
The 426 Upgrade Required status code is a powerful tool for protocol transition and enforcement. It allows servers to clearly communicate when a different protocol is required while providing the necessary information for clients to upgrade. This status code is particularly valuable in scenarios where security considerations necessitate HTTPS, performance improvements require newer HTTP versions, or real-time functionality demands WebSocket connections. By including the Upgrade header, servers can explicitly indicate which protocol(s) clients should use for successful communication.