Empty result is not a failure
An empty array usually means there was no data for this request, not that the API is broken — a malformed code, a market holiday, or data that has not been disclosed yet all look like this. Empty results do not consume quota; work through the list below first.
Two fields tell you everything
An empty result is explicit here:
{ "ok": false, "endpoint": "quote", "tier": "free", "elapsed_ms": 700, "source": "multi", "data": [] }
- The HTTP status is still 200 (the envelope is the body);
ok: falsemeans no data was retrieved anddatais an empty array;- Conversely, when
okis true,datais never empty — an empty result never masquerades as success.
Which empty results are normal
Most common first:
| Situation | What you see | What to do |
|---|---|---|
| Malformed code | ok:false + empty array |
By far the most common. No prefix, dot notation and an uppercase prefix all return empty ⇒ see the code format reference |
| Code does not exist | same | Confirm the code with /v1/search |
| This instrument has nothing for this dataset | empty array | e.g. not on the Dragon-Tiger list means there is no Dragon-Tiger data — that is normal |
| Data not yet disclosed | empty / with an explanation | e.g. margin data or financials before the disclosure date — the data source explains why |
| Unsupported code for that endpoint | empty array | /v1/snapshot supports A-shares only; Hong Kong or US codes return empty (rather than wrong data) |
| Outside the minute-bar window | HTTP 422 + coverage message | Minute bars (period=m1…m120) cover the last month only; a range entirely outside the window returns 422 — use period=day for longer history |
| Minute bars for a symbol that has none | HTTP 422 + explanation (⛔ not an empty array) | Beijing Stock Exchange / futures / forex / US indices have no minute bars; use /v1/minute for intraday Beijing data — see the cross-market reference |
⚠️ A market holiday is not an “empty” result — quotes return the last trading day’s data, and the data date is in date ⇒ see data freshness.
Empty results do not consume quota
If no data was retrieved, you are not charged and no anonymous quota is used — data-source failures, empty results and parameter-driven empties all refund the call.
Telling a normal empty result from a real failure
- Check the HTTP status — 200 means a business result; 4xx / 5xx means a request-layer problem.
- Check whether
okexists — ifokis present it is the envelope (a business result); if the top level iserrorordetailwith nook, it is a request-layer error. - Check the value of
ok—ok:falsewith emptydatameans no data this time; a fetch failure returns 502 withRetry-After, not 200. - Check whether
degradedis present —degraded: truemeans the data source was temporarily unavailable (for example, briefly rate limited), not that this instrument has no data; the response also carriesreasonandretry_after_s(how many seconds until you can retry). Retrying shortly usually works — do not treat it as “no data”.
Common misuses
- Assuming the API is down because the array is empty — check the code format first; that is the usual cause.
- Reading
data[0]without checkingok— an empty array raises an index error. - Treating “no data for this instrument” as a failure — not being on a list, or data not yet disclosed, is a normal empty result.
- Treating
degraded: trueas “no data” — it is a temporary miss; retrying afterretry_after_sseconds usually works. - Calling
snapshotwith a Hong Kong or US code — A-shares only; it returns empty. - Requesting minute bars for a date more than a month back — outside the window, so it returns empty (minute bars cover the last month only).
Last updated: 2026-10-19
The empty-result rules come from the data-layer implementation; the code-format cases and HTTP status codes were measured live on 2026-10-05; minute-bar window and symbol limits checked against the live openapi on 2026-10-07; the degraded field was measured live on 2026-10-19.