错误信封
所有错误响应共用一个形状。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 格式。options 域的合约参数校验使用400 VALIDATION_ERROR（也包括到期日不合法）；请以实际 code 分支处理。合约代码形如 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 检查。仅仅暂未拿到报价不等于已确认不存在，仍可能返回 503。
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 响应头）。成功数据响应按端点计量；缓存命中也扣额度，报价按实际成功合约数计，见配额规则。
IN_FLIGHT_EXCEEDED — 429
同时在途的请求超过 5 个，或同时有超过 1 个 flow 请求在途。降低并发，等在途请求完成后再发。CIRCUIT_OPEN — 429
服务端熔断暂时开启（通常由持续异常流量触发）。按Retry-After 退避，稍后自动恢复。
期权报价：单查与批量失败
最新报价单查使用本页的错误信封；批量通过请求校验后可以返回 HTTP200，并在 data.unavailable 中逐项报告失败：
每个失败项包含
contract_symbol、status、retry_after_seconds。即使不可恢复项含有秒数，也不表示应自动重试；先按 status 判断。单查相应的不可恢复错误为 recoverable: false。
批量只重试可恢复的失败合约；重新请求已成功的合约会再次计费。quotes 为空、全部合约都在 unavailable 中也可以是 200，此时消耗 0 units；HTTP 状态本身不能代替逐项判断。请求级的鉴权、参数校验、配额或并发拒绝仍使用顶层错误信封。
服务端
UPSTREAM_ERROR — 502
数据链路故障。部分端点支持旧值兜底（见数据新鲜度），出现本错误说明该请求无法降级；稍后重试。期权最新报价的失败处理见逐项说明。UPSTREAM_TIMEOUT — 504
数据链路超时。同上，稍后重试。INTERNAL_ERROR — 500
未预期的服务端错误。稍后重试；持续出现时请附request_id 反馈。
还是解决不了？
来 Discord 社区交流：描述你的问题，附上响应里的request_id 与发生时间（含时区），能大幅加快定位。文档没讲清楚的地方也欢迎直接提——它会变成下一次更新。