Skip to main content

​
三层限制

配额与限流按账户计，同一账户的多个 Key 共享同一份额度。

​
配额怎么计

计量接口成功返回数据就会扣额度，_meta.cache_hit 的值不影响计费。 最新报价中的 bid、ask、mid 不分别计费；重复查询相同价格也会再次计费。 批量报价需要余额覆盖请求的不同合约数量，实际只按成功返回数量扣减。例如请求 50 张不同合约，需要至少 50 units 余额；最终返回 20 张则只扣 20 units。余额不足时返回 429 QUOTA_EXHAUSTED，不会先返回能负担的部分。 具体来说，以下情况全部零消耗：
  • 参数错误（400）、鉴权失败（401 / 402 / 403）、限流（429）
  • 数据尚未就绪的 202（见数据新鲜度）；后续重试成功返回数据时按该端点计费
  • 404、422 与服务端错误（5xx）
  • GET /v1/discover、/v1/health、/v1/openapi.json（自描述与元数据端点免费）
测试 Key 不扣月配额，但仍受速率与并发限制。查询 discover、参数错误或数据未就绪的响应不扣额度；用计量数据端点「探测」并成功拿到数据，仍按上述规则扣减。

​
实时余量

每个响应都携带余量头：
也可以随时调 GET /v1/discover（免费）拿同样的信息。429 响应额外携带 Retry-After（秒）。 _meta.quota_remaining_pct 是月配额剩余百分比，不是本次请求费用，也不是报价新鲜度。余量头与该百分比反映本次请求扣减前的余额，尚未扣除本次成功响应的消耗；百分比四舍五入到一位小数，少量调用后仍可能显示 100。需要查询余量时用 discover。 批量报价遇到限流时，按逐项状态退避，只重试可恢复的失败合约，避免对已成功的报价重复计费。

​
自动化程序的建议

  • 尊重 Retry-After：收到 429 后按头部等待，不要立即重试。
  • 控制并发在 5 以内；批量拉取时串行加小间隔比并发冲击更快跑完。
  • 长期任务在启动时查一次 discover 的 monthly_remaining，接近耗尽时降频。
  • 配额在每月第一天重置（精确时刻以 X-Quota-Reset-At 为准）。