入门

响应与错误

所有响应都采用相同的结构。本页介绍响应包装、如何缩减其大小、如何解读空字段，以及每个错误码的含义。

#标准响应包装

响应

{
  "status": "ok",
  "timestamp": 1775648290510,
  "data_type": "basis",
  "data": {
    "basis_value": 42.18,
    "basis_pct": 0.059,
    "futures_price": 71462.51,
    "spot_price": 71420.33,
    "timestamp": "2026-08-29T11:38:00+00:00"
  }
}

字段	类型	说明
`status`	string	ok 或 error。
`timestamp`	integer	响应生成的时刻，以自 Unix 纪元起的毫秒数表示。绝不是数据的时间戳。
`data_type`	string	返回类型的名称。无需依赖调用路径即可分发响应，适用于客户端经由队列或缓存的情况。
`data`	object \| array \| null	数据主体。当指标在所请求窗口内没有数据时为 null。

需要了解的两个例外

有三个接口不使用这种包装，而是返回各自的结构：/v1/health、/v1/status 和 POST /v1/indicators，后者自行构建响应。前两个是探测接口，第三个返回一个按你的标识符索引的 indicators 对象。

#缩减响应

?fields= 参数将 data 限制为所请求的字段：以逗号分隔的列表，嵌套字段用点号表示。在一千行的序列中如果只用两列，响应也会相应缩小。

curl

# The full response
curl -H "X-API-KEY: $BYTNODE_KEY" \
  "https://api.bytnode.com/v1/basis?symbol=BTCUSDT"

# Two fields only
curl -H "X-API-KEY: $BYTNODE_KEY" \
  "https://api.bytnode.com/v1/basis?symbol=BTCUSDT&fields=basis_pct,timestamp"

# Dotted notation for a nested field
curl -H "X-API-KEY: $BYTNODE_KEY" \
  "https://api.bytnode.com/v1/options/summary?asset=BTC&fields=open_interest.total_usd"

未知字段会被拒绝，并建议最接近的字段，而不是默不作声：

422

{
  "detail": "Champ inconnu : 'basis_percent'. Vouliez-vous dire 'basis_pct' ?"
}

#解读空字段

null 或空列表并不能证明现象不存在：它也可能意味着该现象对这个资产根本不存在。混淆两者会导致错误结论，比如资产是没有期货市场的稳定币时，却说“没有爆仓”。

快照通过 unavailable 键消除歧义，该键仅在至少一个请求字段为空时出现：

原因	类型	说明
`not_applicable`	structural	该指标在此没有意义：在现货稳定币上请求源自期货市场的字段，或在 BTC 和 ETH 以外的资产上请求期权。无论采集多少数据都不会改变。
`no_api_key`	configuration	上游数据源未接入本安装：数据从未被采集。这是基础设施缺失，而非市场事实。
`no_data`	market	在所请求窗口内确实没有数据。唯一可以据此得出结论的情况。

详细说明，以及表示某个数字基于多少个交易所计算的 coverage 键，见快照页面。要提前了解某个资产能提供什么，请查询其能力报告。

#错误

错误详情由 detail 键给出。与方案相关的拒绝（速率限制、月度配额、数据族、数据流、密钥）还会带有说明原因的 X-Deny-Reason 响应头；基于时间的拒绝会在正文中加入 retry_after，并附 Retry-After 响应头：速率限制为一秒，月度配额为一小时。

{
  "status": "error",
  "timestamp": 1775648290510,
  "detail": "Debit depasse : votre offre autorise un nombre limite de requetes par minute.",
  "retry_after": 1
}

状态码	最常见原因	如何处理
`400` 请求被拒绝	交易对未知或已停用、深度超过该字段上限、指标参数越界。	响应正文会指出出错的值；如果是交易对，还会列出可接受的交易对。
`403` 被方案或 API 密钥拒绝	四种原因，由 X-Deny-Reason 响应头指明：API 密钥缺失、无效或已吊销（key）；数据族不在方案内（family）；WebSocket 数据流不在方案内（websocket）；或历史深度超出方案窗口，其 detail 以 « Profondeur d’historique hors offre » 开头。	对于 key，请确认请求头确实已发送：部分 HTTP 客户端在重定向后会丢失它。对于 family 和 websocket，数据存在但不在你的方案中。对于深度，detail 会给出可使用的最大 limit。
`422` 参数缺失或格式错误	缺少 symbol、周期不在列表中、请求多周期字段时缺少 @tf 后缀、?fields= 中有未知字段、JSON 正文无效。	对于 ?fields=，响应会建议最接近的字段。对于周期，会列出可接受的值。
`429` 超出速率或配额	每分钟请求数超过方案允许，或突发过于密集（X-Deny-Reason: rate，Retry-After: 1）；或账户月度配额已用尽（X-Deny-Reason: quota，Retry-After: 3600）。	对于 rate，等待 Retry-After 给出的秒数。对于 quota，计数在每月第一天（UTC）重置；你也可以在控制台更换方案。
`503` 暂时不可用	某个读取依赖正在恢复，或数据流的同时连接数已达上限。	在 Retry-After 给出的延迟后重试。此错误本质上是暂时的。
`500` 意外错误	服务端故障，绝不是由请求引起。	请重试；若问题持续，请附上响应中的时间戳报告给我们。

错误码页面逐一介绍每种情况，附准确的消息，以及指标和实时数据流特有的错误。

#响应头

正常响应中没有计数类响应头：配额状态在控制台中查看，达到 80% 时会提醒，首次请求被拒时再次提醒。只有在拒绝时才会出现两个响应头。

响应头	类型	说明
`X-Deny-Reason`	string	与方案相关的拒绝原因：rate（速率限制）、quota（月度配额）、family（数据族不在方案内）、websocket（数据流不在方案内）或 key（密钥缺失、无效或已吊销）。
`Retry-After`	integer	出现在 429 和 503 中。重试前需要等待的秒数：超出速率限制为 1，月度配额用尽为 3600。请遵守它，而不是自行设定延迟。