> Source: https://ashareapi.com/wiki/envelope/  ·  Markdown version for LLMs / AI agents

参考

# 返回信封字段
 每个端点返回的外层结构都一样，共六个字段。数据本身在 data 里，形态不止一种；另外有些错误（缺参数、超限、付费端点没带 Key）走的是另一套返回，别按信封去解析。

## 长什么样

 除 `/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**。其余错误码见[错误码与限流说明](/docs/errors)。


## `/v1/health` 是例外

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

```
{ "ok": true, "uptime_s": 123456, "data_ready": true, "tiers": ["free", "pro"] }
```
 `data_ready` 为 `true` 表示数据通道可用。


 最后更新: 2026-10-05
 字段与失败语义取自 2026-10-05 线上真实返回与端点定义；错误返回形状实测于 /v1/kline 等免费端点。

 接着看

-
[错误码与限流说明](/docs/errors)

-
[全部端点清单](/endpoints)

 [← 全部 Wiki](/wiki)