Double 11 annual ¥1,699/yrView
Reference

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: false means no data was retrieved and data is an empty array;
  • Conversely, when ok is true, data is 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

  1. Check the HTTP status — 200 means a business result; 4xx / 5xx means a request-layer problem.
  2. Check whether ok exists — if ok is present it is the envelope (a business result); if the top level is error or detail with no ok, it is a request-layer error.
  3. Check the value of ok — ok:false with empty data means no data this time; a fetch failure returns 502 with Retry-After, not 200.
  4. Check whether degraded is present — degraded: true means the data source was temporarily unavailable (for example, briefly rate limited), not that this instrument has no data; the response also carries reason and retry_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 checking ok — 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: true as “no data” — it is a temporary miss; retrying after retry_after_s seconds usually works.
  • Calling snapshot with 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.