1. 课程导入与排障地图

在行情接入类项目中，权限错误是最常见、也最容易被误判的一类故障。它表面上往往只表现为“连不上”“没数据”，但根因可能落在账号权限、密钥签名、IP 白名单、订阅范围、频率限制、行情等级、环境配置等不同层面。如果一上来就改代码或重启进程，很容易在错误方向上反复消耗时间。本课程用 30 个真实场景拆解行情接口权限错误的排查方法，本节先建立一张“排障地图”：认清典型表现、判断影响范围、掌握通用排查流程，并对后续 30 例形成整体认知。

一、权限错误的典型表现

行情接口的权限问题很少直接返回一句“权限不足”。不同厂商的网关会把鉴权失败、订阅越权、限流拒绝包装成不同形态，常见表现可归为四类：

• 连接层被拒：TCP/TLS 握手失败、HTTP 返回 401/403、WebSocket 在 upgrade 阶段被断开，通常伴随 Unauthorized、Forbidden、invalid api key 等字样。
• 鉴权通过但订阅失败：登录成功，订阅某合约或某档行情时返回 subscription failed、no permission for this symbol，说明账号存在但权限范围不够。
• 静默无数据：连接正常、心跳正常，但行情推送为空或长时间不更新。这类最隐蔽，往往是订阅了无权限的频道，服务端选择丢弃而非报错。
• 间歇性拒绝：平时可用，高峰或高频请求时出现 429 Too Many Requests、rate limit exceeded，属于频率权限维度的问题。

需要强调：“无数据”不等于“无权限”。网络中断、订阅参数写错、合约代码大小写不一致、时区导致的时间过滤，都可能造成空推送。排障的第一步不是下结论，而是把现象归类到上面四类中的哪一类。

二、影响范围如何快速界定

界定影响范围能大幅缩小根因空间。建议从三个维度交叉判断：

• 单账号还是多账号：只有一个账号异常，优先怀疑密钥、权限等级、IP 绑定；所有账号同时异常，优先怀疑出口 IP 变更、网关地址、证书或厂商侧故障。
• 单接口还是全接口：只有 WebSocket 行情异常而 REST 快照正常，问题多在订阅频道或长连接鉴权；全部接口 401，则集中在密钥与签名。
• 单市场还是全市场：只有某个交易所或某类品种（如期权、Level-2）失败，通常是行情等级或品种授权未开通。

三、通用排障流程

下图给出本节的核心排障地图，按“现象归类 → 分层定位 → 验证修复”的顺序组织，后续 30 例都可挂接到这张图上：

流程的关键在于“由外到内、逐层排除”。先确认网络与出口 IP 是否被白名单接纳，再验证密钥与签名是否正确，然后核对账号权限与订阅参数，最后检查频率配额。每一层都应有可观察的证据，例如 HTTP 状态码、返回体错误码、服务端日志、抓包结果，而不是凭经验猜测。

四、一个最小复现示例

假设某行情客户端启动后 WebSocket 连接成功，但订阅 BTC-USDT 的深度频道后长时间无推送。按地图排查：先用同一密钥请求 REST 私有接口，返回 200，说明密钥与签名正常；再检查订阅报文，发现频道名写成了 depth，而该交易所要求 books 或 depth5 这类带档位的名称。修正后推送恢复。这个例子说明：连接成功不代表订阅成功，订阅报文本身也是权限校验的一部分。

# 示例：最小复现订阅报文（参数为教学示例，非真实厂商格式）
{
  "op": "subscribe",
  "args": [
    { "channel": "books5", "instId": "BTC-USDT" }
  ]
}
# 若返回 {"event":"error","code":"60012","msg":"Invalid channel"}，
# 优先核对频道名与档位，而非怀疑密钥。

五、30 例场景概览与学习建议

后续 30 例按根因聚类：密钥签名类 8 例（密钥错配、时间戳偏移、签名串顺序、编码差异等）、IP 与网络类 6 例（白名单未加、出口 IP 漂移、代理改写、证书链等）、订阅参数类 7 例（频道名、合约码大小写、深度档位、环境地址混用等）、行情等级类 5 例（Level-1/Level-2 未开通、品种未授权、只读密钥误用等）、限流配额类 4 例（QPS 超限、并发连接数、订阅数上限、重连风暴）。

学习时建议每例都按“现象 → 证据 → 根因 → 修复 → 预防”五步记录，并沉淀成自己的检查清单。真正提升排障效率的，不是记住某个错误码，而是形成“先归类、再分层、用证据说话”的稳定方法。本节的地图就是这套方法的骨架，后续每一例都是骨架上的一个具体节点。