426

Upgrade Required

4xx Client Error

Back to list.md

ELI5

You need to upgrade to a newer or different protocol to access this. It's like needing to update your app to continue using it.

Server perspective

Use 426 when the server refuses the current protocol but is willing to continue after the client upgrades.

When to use

•Return 426 when a specific protocol upgrade is required for the request to succeed
•Use it when the client must switch protocols rather than simply authenticate or change payload shape
•Requiring WebSocket upgrade for certain endpoints
•Requiring an upgrade from HTTP/1.1 to h2c (clear-text HTTP/2) before processing the request
•Transitioning to more secure protocols

How to respond

•Include Upgrade with acceptable protocols and send Connection: Upgrade
•Explain the required protocol clearly when clients may not recognize the need automatically

Headers to consider

•Upgrade
•Connection

Response body

•Optionally include a concise explanation of the required protocol upgrade.

Server-side pitfalls

•Do not use 426 when protocol upgrade is optional
•Do not confuse 426 with 505, which is about unsupported HTTP versions rather than an offered upgrade path
•Protocol version not supported (use 505 HTTP Version Not Supported)
•Bad request format (use 400 Bad Request)
•When protocol upgrade is optional

Examples

WebSocket upgrade required

Request:GET https://api.example.test/websocket-endpoint

Response:

426 Upgrade Required

# Headers
Upgrade: websocket
Connection: Upgrade

Endpoint only available via WebSocket protocol

References

Related Status Codes

HTTP Version Not Supported

You're speaking an old or new version of HTTP that I don't understand. Please use a version I support.

Bad Request

Your request doesn't make sense or has mistakes in it. Check what you're sending and try again.