> ## Documentation Index
> Fetch the complete documentation index at: https://docs.decibel.trade/llms.txt
> Use this file to discover all available pages before exploring further.

# Connection Management

> Connect, authenticate, subscribe, and recover WebSocket sessions

This page covers WebSocket connection lifecycle, auth headers, topic subscription format, and reconnection behavior.

## Timeout

Maximum session timeout is 1 hour. Clients must reconnect and restore subscriptions.

## Heartbeat

The server sends WebSocket ping frames every 30 seconds. The keepalive timer is refreshed when:

* A pong frame is received
* Any subscribe or unsubscribe activity occurs

## Authentication and Gateway Boundary

Use `Sec-WebSocket-Protocol`:

```
Sec-WebSocket-Protocol: decibel, <API_KEY>
```

* `decibel` is the accepted subprotocol
* `<API_KEY>` is your bearer token from [Geomi](https://geomi.dev/docs/start)

Implementation note: the WebSocket service itself enforces protocol/topic/message shape and subscription limits. API-key validation is typically enforced at the gateway/proxy layer before traffic reaches the service.

See [REST Authentication](/api-reference/rest/authentication) for credential setup.

## Subscribe/Unsubscribe

Send JSON with `method` and `topic`:

```json theme={null}
{"method":"subscribe","topic":"account_open_orders:0x54011252d627054ccf3401755ef1b068b740f8a1c45886354d1eef549d5907ba"}
```

### Success Response

```json theme={null}
{"success":true,"method":"subscribe","topic":"account_open_orders:0x54011252d627054ccf3401755ef1b068b740f8a1c45886354d1eef549d5907ba"}
```

### Error Response

```json theme={null}
{"success":false,"method":"subscribe","topic":"asd:0x54011252d627054ccf3401755ef1b068b740f8a1c45886354d1eef549d5907ba","error":"Unknown topic type 'asd'"}
```

To unsubscribe, use `"method":"unsubscribe"` with the same topic.

## Handling Reconnection

Since the maximum session timeout is 1 hour, your client must handle reconnections gracefully.

### Best Practices

1. Implement exponential backoff for reconnection attempts
2. Track active subscriptions to restore them after reconnecting
3. Use sequence numbers to detect missed messages (for orderbook updates)
4. For `withdraw_queue`, backfill full state from `GET /api/v1/withdraw_queue` and merge WS deltas by `request_id`.

## Error Messages

Error responses use the same format as subscribe/unsubscribe responses:

```json theme={null}
{
  "success": false,
  "method": "subscribe",
  "topic": "depth:invalid_address",
  "error": "Invalid market address 'invalid_address' for depth topic"
}
```

### Common Errors

| Error                                                        | Cause                                                                         |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| `Unknown topic type '{name}'`                                | Unrecognized channel name                                                     |
| `Missing user address for {topic} topic`                     | Topic requires a user/account address but none provided                       |
| `Missing market address for {topic} topic`                   | Topic requires a market address but none provided                             |
| `Invalid user address '{addr}'`                              | Malformed address                                                             |
| `Invalid market address '{addr}'`                            | Malformed address                                                             |
| `Invalid aggregation level '{level}' for depth topic`        | Must be one of: `1`, `2`, `5`, `10`, `100`, `1000`                            |
| `Invalid interval '{interval}' for market_candlestick topic` | Must be one of: `1m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `1d`, `1w`, `1mo` |
| `Maximum client topic subscription count of 150 reached`     | Too many active subscriptions on one connection                               |

## Related

<CardGroup cols={2}>
  <Card title="WebSocket Overview" href="/api-reference/websocket/overview">
    Channel catalog and topic names
  </Card>

  <Card title="Authentication" href="/api-reference/rest/authentication">
    Token and header setup
  </Card>
</CardGroup>