WebSocket Close Codes Explained: A guide to Connection Status Codes

WebSocket connections, unlike traditional HTTP requests, maintain a persistent connection between client and server. When these connections end, they do so with specific close codes that provide valuable information about why the connection was terminated. Let's dive into these codes and understand their significance. Normal Closure Scenarios (1000-1001) 1000 - Normal Closure This is the "happy path" of WebSocket closures. When you see this code, it means the connection completed its purpose and was closed gracefully. Think of it like hanging up a phone call after saying goodbye. 1001 - Going Away The server or client is going down for maintenance or a browser tab is closing. It's like telling your friend "I need to go now" before ending a conversation. This gives the other party a chance to prepare for disconnection. Protocol and Data Issues (1002-1003) 1002 - Protocol Error Something went wrong with the WebSocket protocol itself. It's similar to two people speaking different languages - communication becomes impossible. 1003 - Unsupported Data The endpoint received data it couldn't handle. Imagine sending an image file when the receiver only expects text messages. Connection Abnormalities (1005-1006) 1005 - No Status Received A connection closed without explicitly stating why. This is like someone hanging up the phone without saying anything. 1006 - Abnormal Closure The connection was terminated unexpectedly. Think of it as your phone call dropping due to poor signal. Data and Policy Issues (1007-1009) 1007 - Invalid Frame Payload The message contained invalid data. It's like receiving a corrupted file. 1008 - Policy Violation The endpoint is terminating the connection due to a policy breach. Similar to being removed from a chat room for violating rules. 1009 - Message Too Big The message exceeded size limits. Like trying to send a file that's too large via email. Technical Issues (1010-1015) 1010 - Mandatory Extension The client wanted an extension the server couldn't provide. Think of it as needing a specific app feature that isn't available. 1011 - Internal Server Error Something went wrong on the server side. Similar to a restaurant kitchen having problems preparing your order. 1012 - Service Restart The service is restarting. Like a "be right back" sign in a shop window. 1013 - Try Again Later The server is temporarily unable to handle the request. Think of it as a "busy signal" on a phone line. 1015 - TLS Handshake Failure There was a problem with the security handshake. Similar to failing to verify someone's identity before a secure conversation. Best Practices for Handling Close Codes Always implement handlers for at least codes 1000, 1001, and 1006 Log abnormal closures (especially 1006 and 1011) Provide reconnection logic for temporary issues (1012, 1013) Give user feedback for policy violations (1008)

Apr 3, 2025 - 08:22

WebSocket Close Codes Explained: A guide to Connection Status Codes

WebSocket connections, unlike traditional HTTP requests, maintain a persistent connection between client and server. When these connections end, they do so with specific close codes that provide valuable information about why the connection was terminated. Let's dive into these codes and understand their significance.

Normal Closure Scenarios (1000-1001)

1000 - Normal Closure

This is the "happy path" of WebSocket closures. When you see this code, it means the connection completed its purpose and was closed gracefully. Think of it like hanging up a phone call after saying goodbye.

1001 - Going Away

The server or client is going down for maintenance or a browser tab is closing. It's like telling your friend "I need to go now" before ending a conversation. This gives the other party a chance to prepare for disconnection.

Protocol and Data Issues (1002-1003)

1002 - Protocol Error

Something went wrong with the WebSocket protocol itself. It's similar to two people speaking different languages - communication becomes impossible.

1003 - Unsupported Data

The endpoint received data it couldn't handle. Imagine sending an image file when the receiver only expects text messages.

Connection Abnormalities (1005-1006)

1005 - No Status Received

A connection closed without explicitly stating why. This is like someone hanging up the phone without saying anything.

1006 - Abnormal Closure

The connection was terminated unexpectedly. Think of it as your phone call dropping due to poor signal.

Data and Policy Issues (1007-1009)

1007 - Invalid Frame Payload

The message contained invalid data. It's like receiving a corrupted file.

1008 - Policy Violation

The endpoint is terminating the connection due to a policy breach. Similar to being removed from a chat room for violating rules.

1009 - Message Too Big

The message exceeded size limits. Like trying to send a file that's too large via email.

Technical Issues (1010-1015)

1010 - Mandatory Extension

The client wanted an extension the server couldn't provide. Think of it as needing a specific app feature that isn't available.

1011 - Internal Server Error

Something went wrong on the server side. Similar to a restaurant kitchen having problems preparing your order.

1012 - Service Restart

The service is restarting. Like a "be right back" sign in a shop window.

1013 - Try Again Later

The server is temporarily unable to handle the request. Think of it as a "busy signal" on a phone line.

1015 - TLS Handshake Failure

There was a problem with the security handshake. Similar to failing to verify someone's identity before a secure conversation.

Best Practices for Handling Close Codes

Always implement handlers for at least codes 1000, 1001, and 1006
Log abnormal closures (especially 1006 and 1011)
Provide reconnection logic for temporary issues (1012, 1013)
Give user feedback for policy violations (1008)