错误码

WebSocket 行情推送涉及两类错误码，分别来自不同层级：

两类错误码互相独立，码值范围不重叠，可通过数值范围直接区分。

通道错误码

通道错误发生在请求到达业务逻辑之前，由 WebSocket 网关或鉴权服务返回。

json

{
  "id": "req-001",
  "code": 4002,
  "msg": "auth_failed"
}

注意：字段名为 msg，与订阅响应的 message 字段不同。

code	含义	常见原因	处理建议
`4000`	请求格式错误	发送的帧结构不符合协议，如 JSON 格式有误、`action` 字段为空。	检查请求帧格式，修复后重新发送。
`4001`	尚未完成鉴权	在鉴权成功之前发送了业务请求。	先完成 Auth 鉴权，收到 `session_id` 后再发送业务请求。
`4002`	鉴权失败	`credential_id` 不存在、签名验证不通过、Bearer Token 已过期或无效。	检查凭证和签名逻辑；OAuth2 场景需先刷新 Token 再重新建立连接。
`4003`	权限不足	当前凭证的授权范围（scope）不包含所请求的接口权限。	确认所用凭证是否已授权该接口；如使用 OAuth2，检查授权时申请的 scope。
`4004`	接口不存在	`action` 填写有误，或请求了服务端未开放的接口。	核对接口文档，确认 `action` 名称拼写正确。
`5000`	服务内部错误	服务端处理请求时发生意外异常。	可联系服务端排查；不建议自动重试。
`5002`	网关错误	服务端网络异常，请求未能送达后端。	稍后重试；持续出现请检查网络环境或联系服务端。
`5003`	服务暂时不可用	服务端负载过高，暂时无法处理新请求。	等待片刻后重试，建议加退避策略。
`5004`	请求超时	服务端处理超时，未能在规定时间内返回结果。	稍后重试；持续超时请联系服务端排查。

订阅响应码仅出现在订阅（subscribe）和反订阅（unsubscribe）请求的响应中，由业务层处理后返回。

json

{
  "id": "sub-001",
  "code": 0,
  "message": "success"
}

注意：字段名为 message，与通道错误的 msg 字段不同。

成功示例：

json

{
  "id": "sub-001",
  "code": 0,
  "message": "success"
}

失败示例：

json

{
  "id": "sub-002",
  "code": 4,
  "message": "sub quota exceeded, max=100"
}

code	含义	常见原因	处理建议
`0`	成功	订阅、反订阅或会话清理请求处理成功。	继续接收推送，或更新本地订阅状态。
`1`	必要会话信息缺失	未完成鉴权就发起订阅；连接会话异常；网关未能建立有效用户会话。	重新建立 WebSocket 连接，先完成登录鉴权，再重新订阅。
`2`	不支持的操作类型	`action` 填写错误，或使用了服务端不支持的动作。	检查 `action` 是否为 `subscribe` 或 `unsubscribe`。
`3`	系统异常	服务端进行订阅配额检查时依赖服务暂时不可用。	按退避策略稍后重试；如果持续出现，请联系技术支持并提供请求 ID、时间和返回内容。
`4`	订阅配额不足	当前账号的订阅数量超过上限。	减少订阅标的或数据类型；先反订阅不再使用的标的；确认账号行情权限和配额。
`5`	K 线周期参数非法	`kline.period` 不在支持范围内，或周期格式不正确。	按订阅与反订阅中支持的 K 线周期重新传参。

TIP

收到非 0 响应时，不应把该请求视为已生效。客户端应保持本地订阅状态与服务端响应一致：只有在订阅成功后才标记为已订阅，只有在反订阅成功后才移除本地订阅记录。