426 Upgrade Required: Fix the Protocol Mismatch

Problem

A request returns 426 Upgrade Required instead of the response you expected.

Symptoms

• HTTP Check shows a final status code of 426.
• The same endpoint works from a browser but fails from curl, a script, or an SDK.
• The response carries an Upgrade header naming a protocol like TLS/1.2, h2, or websocket.

What 426 Actually Means

426 is the server saying: I can handle this request, but not over the protocol you’re speaking. It refuses the current protocol and points you at a better one. The status was born in RFC 2817 (2000), which defined 426 specifically so a server could demand a TLS upgrade inside plain HTTP/1.1; RFC 9110 later folded it into the core HTTP semantics.

The important part is the requirement that comes with it: a 426 response MUST include an Upgrade header field listing the protocol token(s) the server will accept. Usually you’ll see Connection: upgrade alongside it. So a correct 426 is never a dead end — it hands you the answer. Read the Upgrade value, resend the request over that protocol, and the healthy outcome is 101 Switching Protocols.

This is what separates 426 from its neighbors. A 505 HTTP Version Not Supported means the server won’t do that HTTP version at all — no upgrade offered. A 400 Bad Request means your request was malformed. A 403 Forbidden means the request was fine but you’re not allowed. 426 means: right request, wrong wire — here’s the wire I want.

Top 3 Causes

1. You called an HTTPS-only endpoint over plain HTTP - The API mandates TLS, so it rejects the cleartext request with 426 and an Upgrade: TLS/1.2 (or higher) header. This is the original RFC 2817 use case and still the most common one in the wild.
2. The endpoint requires HTTP/2 (or a WebSocket handshake) and you sent HTTP/1.1 - Some gRPC gateways, streaming APIs, and real-time endpoints only speak h2 or expect a WebSocket Upgrade. A plain HTTP/1.1 GET has nowhere to go, so the server answers 426 with the protocol it wants.
3. A client library pinned an old protocol - An SDK or HTTP client configured for cleartext or HTTP/1.1-only satisfies none of the server’s requirements. The application code looks right; the transport is wrong.

Diagnose with DechoNet

• HTTP Check to confirm the final code is 426 and read the Upgrade header — that value is the fix, spelled out.
• SSL Check to confirm the origin actually serves TLS on 443, so an Upgrade: TLS/... response is a demand you can satisfy rather than a broken listener.

Resolution Checklist

• Read the Upgrade header in the 426 response — it names the exact protocol the server expects.
• If it names TLS, switch the request to https:// (or add the upgrade handshake) instead of plain HTTP.
• If it names h2 or websocket, enable HTTP/2 or perform the WebSocket handshake in your client.
• Check that your HTTP client or SDK isn’t pinned to cleartext or HTTP/1.1-only.
• Re-send the request over the named protocol and confirm you get 101 Switching Protocols or a normal 2xx.
• Re-run HTTP Check and confirm the response is no longer 426.

When to Escalate

• If the server sends 426 with no Upgrade header, that’s a spec violation — take it to whoever owns the endpoint, because the response is withholding the one thing it’s required to tell you.
• If you’re already using the protocol the Upgrade header names and still get 426, a proxy or gateway in front of the origin is likely rewriting the request; escalate to whoever runs that layer.