Empty result is not a failure

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 upstream 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)

⚠️ 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 — upstream 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; an upstream fetch failure returns 502 with Retry-After, not 200.

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.
• Calling snapshot with a Hong Kong or US code — A-shares only; it returns empty.