空结果不等于故障

先看两个字段

空数据在我们这里是明确的：

{ "ok": false, "endpoint": "quote", "tier": "free", "elapsed_ms": 700, "source": "multi", "data": [] }

• HTTP 状态码仍是 200（信封本身就是返回体）；
• ok: false 表示这次没取到数据，data 是空数组；
• 反过来，ok: true 时 data 一定有内容 —— 空结果不会伪装成成功。

哪些“空”是正常的

按从常见到少见排：

情况	表现	怎么办
代码格式写错	ok:false + 空数组	最常见。不带前缀、点号写法、大写前缀全都返回空 ⇒ 见代码格式速查
代码不存在	同上	用 /v1/search 按名称确认代码
这只票当天没有这项数据	空数组	比如没上榜就没有龙虎榜数据，这是正常的
数据尚未披露	空 / 带说明	如两融、财报在披露日之前 —— 上游会给出原因
传了不支持的代码	空数组	/v1/snapshot 只支持 A 股，传港股 / 美股返回空（不返回错数据）

⚠️ 非交易日不是“空” —— 行情会返回最近交易日的数据，数据日期看 date ⇒ 见数据时间口径。

空结果不扣次数

取不到数据就不计费、也不占匿名额度 —— 上游失败、空结果、参数导致的空，次数都会退回来。

怎么区分“正常的空”和“真故障”

1. 看 HTTP 状态码 —— 200 是业务结果；4xx / 5xx 才是请求层的问题。
2. 看有没有 ok 字段 —— 有 ok 就是信封（业务结果）；没有 ok、顶层是 error 或 detail，就是请求层错误。
3. 看 ok 的值 —— ok:false + data 空 = 这次没数据；上游取数失败会返回 502 并带 Retry-After，不是 200。

常见误用

• 看到空数组就以为接口挂了 —— 先查代码格式，这是最常见的原因。
• 不判 ok 就取 data[0] —— 空数组会直接报索引错误。
• 把“这只票没有这项数据”当故障 —— 没上榜、未披露都是正常空。
• 拿 snapshot 查港股 / 美股 —— 只支持 A 股，会返回空。