> 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/getting-started/error-codes/websocket.md).

# WebSocket错误码

Websocket错误码说明

业务错误通常为 WS 文本帧中的 JSON：`{"code":506,"msg":"...","traceId":"..."}`。错误使用 `traceId`；成功订阅应答使用 `trace`。部分订阅失败帧带 `Subscribe fail:` 前缀，也有纯文本错误，需兼容处理。

**不要用 REST 的 `ret` 表解读这些数字。** 例如 REST `508` 是品种不存在，WS `508` 是 API Key 过期。REST 见 [HTTP错误码](/getting-started/error-codes/http.md)。频率与连接数见 [WebSocket限制](/getting-started/api-limitation/websocket.md)。

订阅应答 `10001` / `10004` / `10007` 的 `msg=ok` 只表示帧被收下。`business` 与品种市场不一致时仍可能 ack，但之后不推行情。

连接成功欢迎帧 `{"code":200,"msg":"ws connect success"}` **不是错误**。`business=stock` 时还可能先收到一段纯文本欢迎语。

### 订阅失败帧：带前缀，不是裸 JSON

部分订阅被拒时，服务端返回以 `Subscribe fail:` 开头的**文本帧**（冒号后还有一个空格）。直接对整帧做 `JSON.parse` / `json.loads` 会抛异常；如果代码在这里把解析失败的帧静默丢掉，现象就是「连上了、订阅也发出去了，但一直没有行情，也没有任何错误」。

以下为常见形态。`stock` 的配额错误带前缀；`crypto` / `common` 的 `505`、`516` 返回裸 JSON。免费标的权限错误 `521` 带前缀：

| 触发条件               | 帧内容                                                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------------------------------- |
| 单连接订阅品种超限（505）     | `Subscribe fail: {"traceId":"...","code":505,"msg":"Single WS subscribe exceeds the limit 200"}`                  |
| 所有连接订阅总数超限（516）    | `Subscribe fail: {"traceId":"...","code":516,"msg":"All WS subscribe exceeds the limit 6000"}`                    |
| `business` 与品种类型不符 | `Subscribe fail: Some product is not stock product like:BTCUSDT.Business stock can only subscribe stock products` |
| 套餐未包含该市场           | `Subscribe fail: No access to the following market data:JP`                                                       |

免费标的权限错误示例：

```
Subscribe fail: {"traceId":"request-1","code":521,"msg":"No permission：<symbol>"}
```

上述错误 JSON 的字段名是 **`traceId`**。`521` 在行情订阅阶段表示无标的权限；新闻握手阶段的同号含义见下表。请求含无权限代码时，本次整批订阅被拒。

推荐处理顺序：

1. 先判断文本是否以 `Subscribe fail:` 开头；是则把前缀连同其后的空格一起剥掉；没有前缀则直接检查原文本。
2. 剩下的部分若以 `{` 开头，按 JSON 解析，取 `code` 走错误码表；否则把整段文本当作错误消息透给上层。
3. **不要原样重发这次订阅。** `business` 不符、无市场/标的权限（含521）、505 这些情况，重发多少次结果都一样；516 可以退避重试，但重试帧同样计入每分钟 60 次的请求额度（见 [WebSocket限制](/getting-started/api-limitation/websocket.md)），无节制重发会触发 `501` 并被服务端断开，然后重连、再超限，形成死循环。

### 应用层错误码

| code | 说明                  | 英文 msg                                                 |
| ---- | ------------------- | ------------------------------------------------------ |
| 200  | 连接成功（欢迎帧）           | ws connect success                                     |
| 500  | 服务异常                | server error                                           |
| 501  | 每分钟请求超限（含心跳，60 次/分） | Request frequency exceed the limit：%s times per minute |
| 502  | 当天请求达上限             | Request frequency for the day upper limit：%s           |
| 503  | K 线数量超限             | Kline quantity exceeds the limit：%s                    |
| 504  | 盘口深度超限              | Orderbook depth exceeds the limit：%s                   |
| 505  | 单连接订阅品种超限           | Single WS subscribe exceeds the limit %s               |
| 506  | 参数错误                | Param error：%s                                         |
| 507  | 参数缺失                | Param lost：%s                                          |
| 508  | API Key 权限已过期       | The apiKey permission has expired                      |
| 509  | API Key 无效          | The apiKey is invalid                                  |
| 510  | API Key 为空          | The apiKey is empty                                    |
| 511  | API Key 在黑名单        | The apiKey is in the blacklist                         |
| 512  | WebSocket 连接数超过套餐   | WebSocket connections exceeds the limit：%s             |
| 513  | 心跳超时                | Websocket heartbeat timeout                            |
| 514  | WS 请求地址错误           | Websocket Url Wrong                                    |
| 515  | 参数不是 JSON           | Param not json，request failed                          |
| 516  | 所有连接订阅总数超限          | All WS subscribe exceeds the limit %s                  |
| 521  | 行情订阅的免费标的权限不足       | No permission：%s                                       |

参数不是 JSON 时，`crypto` / `common` 可能直接发送纯文本 `Param not json，request failed`，不一定包含 `code:515`。API Key 到期也可能以纯文本通知后断开。表中列出的编码不代表每个市场和阶段都保证发送该 JSON。

没有 `427`。连接数超限可能来自应用层 `512`、新闻握手 `521` 或网关 HTTP `429`，应结合发生阶段判断。

### 握手层补充

新闻 / 韩股 / 台股等端口在握手阶段还可能返回：

| code | 说明                                           |
| ---- | -------------------------------------------- |
| 517  | 握手缺少 API Key                                 |
| 518  | API Key 不存在                                  |
| 519  | 无权限（新闻无 news 权限；韩股无订阅权限）                     |
| 520  | 韩/台：代码后缀与市场不符（`.KS` / `.TW`）；新闻：该 key 已有新闻连接 |
| 521  | 新闻握手：服务端连接数达上限                               |

无新闻权限时，`/news` 也可能在 HTTP 握手阶段直接返回 **401**，连接不会建立。

### 网关 / CDN

| HTTP 状态 | 说明      |
| ------- | ------- |
| 401     | 握手认证失败  |
| 404     | 地址不存在   |
| 429     | 网关限流    |
| 499     | 客户端主动断开 |
| 524     | 源站超时    |