Errors
Error codes, what causes them, and what to do about each.
Shape
An error returns a JSON object with a single error key naming the failure, and an HTTP status
that matches its class. The body is never empty and never carries a partial result.
{"error":"network_unavailable"}
Status codes
| Status | Meaning | What to do |
|---|---|---|
200 | Success. The body may still carry an empty series. | Check the series length, not just the status. |
400 | Malformed request. | Fix the parameters before retrying. A retry will fail identically. |
401 | Missing or invalid API key. | Check TRADEFLAGS_API_KEY is set and the key is live. |
403 | Key valid but not entitled to the package or series. | Check your tier. Request an upgrade. |
429 | Rate or quota limit reached. | Back off and retry after the interval given in the Retry-After header. |
500 | The service could not complete the call. | Retry with backoff. If it persists, the series may be unavailable. |
503 | Service or database unreachable. | Check /api/health.php. Retry once the service reports healthy. |
Named errors
These are the error values the service returns. Each names the specific series that could not
be served, so a failing tool identifies itself.
| Error | Meaning |
|---|---|
ads_unavailable | The ADS Business Conditions series could not be read. |
cranex_unavailable | The CRANE-X sentiment snapshot could not be read. |
live_unavailable | The live bundle could not be assembled. |
moirai_hk_unavailable | The Moirai HK forecast bundle could not be read. |
network_unavailable | The supply-chain graph could not be read. |
news_unavailable | The headline feed could not be read. |
trin_scatter_unavailable | The TRIN scatter series could not be read. |
vix_unavailable | The VIX term-structure series could not be read. |
No data | The request was valid but the series holds no rows for that query. The response carries an empty strategies array alongside it. |
Retrying
A 500 or 503 is worth retrying with exponential backoff. A 400 or a
named *_unavailable error on a single series will not be fixed by retrying the same call —
it is either a bad request or a series that is genuinely not published.
Named errors are per series. When one series fails, the response
identifies that series by name rather than failing the whole bundle. A client can then degrade one panel
instead of the page.
Still stuck
Write to contact@tradeflags.com with the error name, the package, the tool and the approximate time of the call. That is enough for us to find the corresponding entry in the request log.
Not investment advice. TradeFlags outputs are computational audit data only. No dealing, advising or
asset-management activity is conducted.