> For the complete documentation index, see [llms.txt](https://docs.infoway.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.infoway.io/websocket-api/heartbeat.md).

# 心跳机制

### API说明

行情客户端需要主动发送应用心跳 `10010`，建议每 **30 秒**发送一次。`stock`、`crypto`、`common` 通道超过 **60 秒**未收到有效的 `10010`，会在后续心跳检查时关闭连接。

WebSocket 协议 Ping 可以收到 Pong，但在上述通道不能替代 `10010`。持续收到行情或只发送订阅消息也不能替代应用心跳。

`ack` 可选：

* 不传或 `0`：只保活，服务端不回包。
* `ack=1`（顶层或 `data.ack`）：服务端回 `10011`。`10011` **不是错误**，客户端可用它确认心跳已收到。顶层 `ack` 与 `data.ack` 同时存在时，以顶层值为准。

心跳计入「每连接每分钟 60 帧」，详见 [WebSocket限制](/getting-started/api-limitation/websocket.md)。

### 请求频率

同一 WebSocket 连接，订阅 + 取消订阅 + 心跳合计限制见 [WebSocket限制](/getting-started/api-limitation/websocket.md)（**1 分钟 60 次**）。超出将断连；断连过多可能封禁 API Key。

### 错误码说明

见 [WebSocket错误码](/getting-started/error-codes/websocket.md)。超时对应 `513`。

### 接口地址

见 [行情地址说明](/getting-started/api-endpoints.md)。

### 请求（协议号：10010）

```json
{
    "code": 10010,
    "trace": "423afec425004bd8a5e02e1ba5f9b2b0"
}
```

需要回包时：

```json
{
    "code": 10010,
    "trace": "423afec425004bd8a5e02e1ba5f9b2b0",
    "ack": 1
}
```

| 参数名     | 类型      | 必填 | 描述            | 示例值                                |
| ------- | ------- | -- | ------------- | ---------------------------------- |
| `code`  | Integer | 是  | 心跳协议号 `10010` | `10010`                            |
| `trace` | String  | 是  | 可追溯 ID        | `423afec425004bd8a5e02e1ba5f9b2b0` |
| `ack`   | Integer | 否  | `1` 时回确认      | `1`                                |

### 应答（协议号：10011，仅 ack=1）

```json
{
    "code": 10011,
    "trace": "423afec425004bd8a5e02e1ba5f9b2b0",
    "msg": "ok"
}
```

| 字段名     | 类型      | 描述        | 示例值                                |
| ------- | ------- | --------- | ---------------------------------- |
| `code`  | Integer | 心跳确认，不是错误 | `10011`                            |
| `trace` | String  | 与请求一致     | `423afec425004bd8a5e02e1ba5f9b2b0` |
| `msg`   | String  | 响应        | `ok`                               |