Switching Protocols

Overview

101 Switching Protocols means the server agreed to the protocol change the client asked for via the Upgrade header. After this response the same TCP connection stops speaking ordinary HTTP and switches to the negotiated protocol.

The most common real-world use is upgrading from HTTP to WebSocket. The Sec-WebSocket-Accept value in the response proves the server validated the client's key, and from that point on the connection carries bidirectional real-time traffic.

When it happens

• When a browser opens a WebSocket connection, it starts the handshake with Connection: Upgrade and Upgrade: websocket; the server accepts by returning 101.
• It is also used, more rarely, for other protocol switches such as upgrading HTTP/1.1 to h2c (cleartext HTTP/2).

Request / Response example

GET /chat HTTP/1.1
Host: example.com
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

In code

const ws = new WebSocket('wss://example.com/chat');
ws.onopen = () => ws.send('hello');
// the 101 handshake happens transparently before onopen

import { WebSocketServer } from 'ws';
const wss = new WebSocketServer({ port: 8080 });
wss.on('connection', s => s.send('welcome')); // library sends 101

Notes

• After 101 the connection leaves the request/response model, so a plain HTTP client or curl cannot easily observe the traffic that follows.
• If the server does not support the upgrade it may answer with an ordinary 200 instead, or send 426 Upgrade Required when it wants to force a specific protocol.
• A WebSocket handshake only succeeds when Sec-WebSocket-Key (request) and Sec-WebSocket-Accept (response) match as a valid pair.

Related status codes

Related headers

Specification