返回信封字段

长什么样

除 /v1/health 外，所有端点成功返回的外层都是这六个字段：

{
  "ok": true,
  "endpoint": "kline",
  "tier": "free",
  "elapsed_ms": 701,
  "source": "multi",
  "data": [ "…这里才是数据…" ]
}

字段	类型	含义
ok	布尔	本次是否取到数据。先看它，再取 data
endpoint	字符串	端点名（如 kline、quote）
tier	字符串	本次请求走的档位（匿名调用是 free；带 Key 则是该 Key 的档位）
elapsed_ms	数字	服务端耗时（毫秒）
source	字符串	数据来源标识
data	视端点而定	真正的数据

data 有哪几种形态

不同端点返回的 data 结构不同，取数前先判类型：

形态	出现在	怎么取
数组（每项一行）	kline、quote、hot …	data[0]，再按字段名取，如 data[0].last
对象	单条记录类端点	直接按字段名取
已排版文本（字符串）	market-overview、changedist …	同时会多出 structured / tables，程序化取数用它们
多段	一次返回多张表的端点	从 tables 里按段取

文本型端点的例子：data 是一段 markdown，同时额外多出两个字段 —— structured 是第一个表（[{列: 值}]），tables 是全部表。data 本身没有被改动：文本客户端照旧用 data，程序客户端用 structured。

source 能信吗

source 是数据来源标识。可以看，但不要写进业务逻辑做判断 —— 它的取值不保证稳定，也不代表某个具体上游。

失败时是什么样

ok: false 表示这次没取到数据（此时 data 可能为空或缺席）。注意两点：

• HTTP 状态码仍是 200（信封本身就是返回体）；
• 先判 ok，再决定要不要用 data。

哪些返回不是信封

下面这几种不走上面那套结构，别按信封去解析：

情况	HTTP	返回长什么样
缺必填参数（如没传 code）	422	{"detail": [{"loc": ["query", "code"], "msg": "Field required", "input": null}]}
付费端点匿名调用	401	{"error": "需要 API Key（此端点属付费层）", "docs": "/docs"}
匿名超限	429	{"error": "匿名限流 …", "pow": { … }, "how_to": "…"}

共同特征：没有 ok 字段，顶层是 error 或 detail。所以健壮的客户端应该先看 HTTP 状态码，再看有没有 ok。其余错误码见错误码与限流说明。

/v1/health 是例外

/v1/health 不返回 data，它返回服务状态：

{ "ok": true, "uptime_s": 123456, "data_ready": true, "tiers": ["free", "pro"] }

data_ready 为 true 表示数据通道可用。