错误信封
所有错误响应共用一个形状。code 是稳定的机器可读标识（本页锚点与之一一对应），message / hint 是给人读的说明，可能随时间改进措辞——程序请匹配 code，不要匹配文案。
recoverable: true 与 retry_after_seconds（body 为权威；Retry-After 响应头同时下发）。反馈问题时请附上 request_id（见页尾）。
除标注外，下列错误响应均不消耗月配额。
鉴权与权限
AUTH_MISSING — 401
请求没有携带Authorization header。按 Authorization: Bearer sk_live_... 携带 Key，见鉴权。
AUTH_INVALID — 401
Key 无效或已被撤销。到账户页确认 Key 状态，必要时重新生成。AUTH_PAUSED — 402
订阅已失效，API 访问随之暂停。Key 未被删除：恢复订阅后同一个 Key 自动恢复可用。SCOPE_INSUFFICIENT — 403
当前 Key 缺少访问该端点所需的 scope。用GET /v1/discover 查看当前 Key 的 access_scope 与可用能力。
KEY_LIMIT_REACHED — 409
已持有 5 个 active Key，无法再生成。先在账户页撤销一个不再使用的 Key。请求校验
VALIDATION_ERROR — 400
查询参数或请求体校验失败（非法日期、非法 cursor、未知参数等）。hint 会指出具体哪一项不合法；修正后重发。
TICKER_INVALID — 400
标的代码不符合该端点的词法要求（如含小写字母、长度超限）。注意这是「写法不合法」；写法合法但不在服务范围的代码返回的是NOT_FOUND 或 READ_MODEL_UNAVAILABLE。
CONTRACT_SYMBOL_INVALID — 400
期权合约代码不符合 OSI 格式。合约代码形如SPY260620C00450000（标的 + 到期 YYMMDD + C/P + 行权价 ×1000 补零），具体以各端点 Reference 为准。
INDEX_UNSUPPORTED — 422
该端点不支持所请求的指数类标的。这是永久性拒绝，重试不会改变结果；改用受支持的标的。RANGE_TOO_DEEP — 404
请求的历史范围早于该数据集的保留窗口。收窄from 到保留窗口内（各数据集的窗口见其文档页）。
RESPONSE_TOO_LARGE — 422
按当前参数生成的响应超出体积上限。API 不会截断 JSON（截断的 JSON 无法解析），而是返回本错误；按hint 收窄查询：降低 limit、缩短时间范围，或使用 format=summary 档位（支持的端点会在 Reference 标注）。
数据可用性
NOT_FOUND — 404
请求的资源不在服务目录内（目录边界，永久语义）。不要重试；用GET /v1/discover 确认当前可用的数据集与覆盖面。
READ_MODEL_UNAVAILABLE — 503
数据属于服务范围但此刻不可用（例如正在准备中或短暂缺失）。按retry_after_seconds 重试。与 404 的分工见数据新鲜度；多轮重试无进展时应检查请求组合是否本身无意义（如已过期日期的快照）。
SERVICE_DISABLED — 503
该能力当前未提供服务，两种可能：能力尚未开放（关注 changelog 了解上线节奏），或短暂的维护 / 恢复窗口（如 Dealer Heatmap 的服务恢复期，通常分钟级）。本错误不携带retry_after_seconds，不适合程序自动重试循环——与 READ_MODEL_UNAVAILABLE（带重试间隔的可自动重试错误）区分处理：收到本错误应降级处理，稍后低频重试；持续数日不恢复则按「未开放」理解。
限流与配额
RATE_LIMITED — 429
超出速率限制（每账户 60 请求/分钟，或 IP 级 200/分钟）。按Retry-After 等待后重试；持续触发说明并发或轮询频率需要下调。
QUOTA_EXHAUSTED — 429
本月 100,000 units 配额已用完。配额每月初重置（精确时刻见X-Quota-Reset-At 响应头）。提醒：只有 200 响应计费，见配额规则。
IN_FLIGHT_EXCEEDED — 429
同时在途的请求超过 5 个。降低并发，等在途请求完成后再发。CIRCUIT_OPEN — 429
服务端熔断暂时开启（通常由持续异常流量触发）。按Retry-After 退避，稍后自动恢复。
服务端
UPSTREAM_ERROR — 502
数据链路故障。数据读取类端点通常会以旧值兜底（见数据新鲜度），出现本错误说明该请求无法降级；稍后重试。UPSTREAM_TIMEOUT — 504
数据链路超时。同上，稍后重试。INTERNAL_ERROR — 500
未预期的服务端错误。稍后重试；持续出现时请附request_id 反馈。
还是解决不了？
来 Discord 社区交流：描述你的问题，附上响应里的request_id 与发生时间（含时区），能大幅加快定位。文档没讲清楚的地方也欢迎直接提——它会变成下一次更新。