Switching Protocols

Server perspective

Use 101 when the client requested a protocol upgrade and the server is switching this connection to that protocol.

When to use

• •Return 101 for successful WebSocket upgrades
• •Use it only when the protocol switch is explicitly requested and supported
• •Use it only when the new protocol can still honor the semantics of the original request on this same connection
• •WebSocket upgrade from HTTP
• •Custom protocol upgrades on the same connection when both sides support them
• •Real-time or bidirectional protocols negotiated through Upgrade

How to respond

• •Include Upgrade in the response and Connection: Upgrade so intermediaries treat the switch correctly
• •After the 101 response, continue satisfying the original request using the new protocol instead of requiring the client to repeat it
• •If the request also used Expect: 100-continue, send 100 before 101

Headers to consider

• •Send Upgrade naming the protocol that will take effect and Connection: Upgrade to scope the header to this connection.

Response body

• •Do not include a regular HTTP response body in the 101 response; the connection switches to the new protocol immediately after the headers.

Server-side pitfalls

• •Do not use 101 unless the client actually requested an upgrade
• •Do not use 101 as a redirect or as a way to move the client to a different connection, TCP socket, or TLS session
• •Do not switch protocols if the new protocol cannot honor the original request semantics
• •Do not use 101 to attempt an HTTP/2 upgrade via the Upgrade header; the h2c upgrade token is obsolete per RFC 9113 and HTTP/2 disallows this mechanism. Modern HTTP/2 connections are negotiated via ALPN at the TLS layer, not via 101.
• •Normal HTTP requests that stay on the same protocol
• •When the request did not ask for an upgrade
• •When intermediaries or infrastructure do not support the switch
• •As a generic redirect to HTTPS

Examples