WebSocket Close Codes

WebSocket close codes

When a WebSocket connection ends, the closing endpoint can send a Close frame containing a numeric status code and an optional reason string. These codes — defined in RFC 6455 and extended through the IANA registry — explain why the socket closed: a clean shutdown, a protocol error, an oversized message, or an application-specific reason of your own. Some codes are reserved and set only by the library (you must never send them yourself), and whole ranges are carved out for application use. Search the reference above by number or keyword.

How it works

A Close frame carries a 2-byte big-endian status code followed by an optional UTF-8 reason of up to 123 bytes. The protocol-defined codes live in 1000–2999. Within that, 1000 is a clean close, 1001–1011 cover protocol, data, policy, and server errors, and a few values (1005, 1006, 1015) are reserved — they describe what happened but must never be transmitted in a frame. The 3000–3999 range is for codes registered with IANA by libraries and frameworks, and 4000–4999 is entirely private: your application can assign its own meanings there without coordinating with anyone. Codes below 1000 are never used.

Tips and examples

• Close cleanly with 1000 Normal Closure when work is done, and let the peer echo a Close frame before the TCP teardown.
• Treat 1006 as a connectivity signal, not an application error — it means the socket dropped without a Close frame, so reconnect with backoff.
• Reserve a 4000–4999 code for each of your own shutdown reasons (e.g. 4001 = session expired, 4002 = kicked by admin) and document them for clients.
• Keep reason strings short and human-readable for logs; never rely on parsing them programmatically since they are not standardized.