A WebSocket bootstrap over HTTP/2 is answered with `:status = 501`, so what has the server said and what should the client do next?

## What the refusal actually means An extended CONNECT answered with `:status = 501` means one thing: the server does not support the protocol named in `:protocol`. The specification says a server **SHOULD** respond this way — it is a recommendation, not an absolute — so a client must also cope with other refusals and with a server that simply errors the stream. What the 501 is **not**: - **Not a subprotocol rejection.** Failing to agree on a `sec-websocket-protocol` value is a different outcome on a tunnel that did open. - **Not a routing or path error.** The server is not saying the resource is missing; it is saying it does not do this kind of request. - **Not transient.** Nothing about the condition will change on the next stream, the next second or the next request. - **Not partial.** There is no half-open socket to clean up. The stream carried a request and a response and that was all. ## Two different failures that look alike from the application From the application's point of view, "the socket did not open" covers two situations with different causes and different fixes. | Situation | What the client saw | What the client should do | |---|---|---| | Server advertised the setting, then refused | `SETTINGS_ENABLE_CONNECT_PROTOCOL` = 1, then a `501` | Fall back to the HTTP/1.1 handshake; record the refusal for this origin | | Server never advertised the setting | no such setting on the connection | Do not send the extended CONNECT at all; go straight to the fallback | The second row is the one clients get wrong. Sending the bootstrap without having seen the advertisement is a client-side protocol error, not an experiment — and the answer you get back tells you nothing you were entitled to ask for. A third situation belongs in the same triage, and it is the one that actually burns engineering time: the request never reached the origin server at all. A hop in the middle that does not implement the extension may refuse the request, may strip what it does not understand, or may fail the stream. Because the class of intermediary, not the origin, decided the outcome, the origin's own logs show nothing and the two ends disagree about what happened. ## Diagnosing it on a link you do not own The hoist console sits at the end of a leased link with hops you cannot inspect. When sockets fail to open, the ordered questions are: 1. **Did the advertisement arrive?** If the setting was never seen on this connection, the client should never have attempted the bootstrap. That is a client bug, and the fallback should have fired already. 2. **Did the refusal come from the far end?** A `501` shaped exactly as the specification describes, arriving with the origin's other responses, suggests the origin. A stream that fails without a status, or a refusal on a connection where ordinary requests succeed, suggests a hop. 3. **Does the HTTP/1.1 path work?** If a socket opens over a separate HTTP/1.1 connection, the socket itself is fine and the bootstrap is what is unsupported. That single test separates "WebSockets are broken here" from "this bootstrap is not available here". ## What a good client does with the answer Cache the verdict per origin, fall back once, and do not re-probe on every socket. A device that re-attempts a refused bootstrap before every connection pays a round trip per socket for information it already has. Equally, do not cache it forever across restarts: server-side support appears when a deployment changes, and a client that decided in 2026 that an origin cannot do this will never notice. ```http # request :method = CONNECT :protocol = websocket :scheme = https :path = /hoist/shaft-3/signals :authority = hoist-control.example:443 # response :status = 501 ``` The absence of any WebSocket field in that response is the tell: nothing was negotiated because nothing was ever going to be.