Errors

The error shape and every error code the API answers, with its cause, what to do and whether to retry.

An error is an HTTP status and

JSON

{ "error": { "code": "window_too_large", "message": "A sentence saying what was wrong and what to do." } }

Branch on code (stable); show or log message (it may change). The SDKs raise typed errors: AuthenticationError (401), PermissionDeniedError (403), NotFoundError (404), ConflictError (409), InvalidRequestError (400, 422), RateLimitError (429), ServiceUnavailableError (502, 503, 504) and APIConnectionError (no answer).

#Every code

This table is generated from the API's own code: every code a route can answer is listed.

Status	Code	Typical cause	What to do	Retry
400	`invalid_cursor`	The cursor came from another route or other parameters, or was edited.	Start again without `cursor`, then follow `meta.next_cursor` as given.	no
400	`invalid_param`	A parameter is missing, malformed or out of range; the message names it.	Fix the parameter; see the operation's reference page.	no
400	`key_in_url`	An API key was sent in the query string.	Send it in `Authorization: Bearer`, and rotate the key: URLs end up in logs.	no
401	`key_expired`	The key passed its expiry date.	Make a new key on Account > Developer API.	no
401	`unauthorized`	No key, a malformed key, or an unknown or revoked key.	Check the header and the key; make a new key if it was revoked.	no
403	`insufficient_scope`	The key does not have the scope this route needs.	Add the scope to the key (or use another key).	no
403	`ip_not_allowed`	The call came from an address outside the key's IP allow list.	Call from an allowed address or widen the allow list.	no
403	`tier_required`	Your tier does not include this route, window or option.	Use what your tier allows, or upgrade.	no
404	`no_data`	Nothing is recorded for this market and window.	Try another window or market.	no
404	`not_available`	This data is not available for this market or venue.	Check /v1/venues and /v1/markets for what each venue offers.	no
404	`not_found`	The thing named (event, series, endpoint, market) does not exist or is not yours.	Check the id.	no
404	`not_in_sandbox`	A sandbox key asked for something the recorded pack does not hold.	Ask for what the sandbox records (see Sandbox), or use a live key.	no
404	`sandbox_not_recorded`	A sandbox key asked for something the recorded pack does not hold; the message lists what it holds.	Ask for a recorded market and window, or use a live key.	no
404	`split_unavailable`	The coin's exchanges (or the pinned venue) publish no long/short split, so a net longs, net shorts or delta picture cannot be drawn.	Use `positions-heatmap` (open interest by price) or another venue.	no
404	`unknown_chart`	There is no chart picture with that name.	Use one of the kinds listed on the operation's reference page (GET /v1/charts/<kind>.png).	no
404	`unknown_widget`	There is no Strata widget picture with that name.	Use one of the widgets listed in the error message, or on the Strata pictures reference page (GET /v1/pictures/strata/<widget>.png).	no
409	`endpoint_disabled`	The webhook endpoint was turned off after repeated failures.	Fix your server, then POST /v1/webhooks/{id}/enable.	no
409	`limit_reached`	You already have as many webhook endpoints as your tier allows.	Delete one, or upgrade.	no
422	`unsupported`	The combination of parameters is not supported by this route.	See the reference page for the supported combinations.	no
422	`window_too_large`	`from` / `to` reach further back, or span longer, than your tier allows on this route.	Shorten the window or page through it; see History windows.	no
429	`quota_exhausted`	This month's request units are used up (X-Quota-Remaining 0; the message gives the reset date).	Wait for the next month (UTC; Retry-After) or upgrade. Retrying sooner does not help.	no
429	`rate_limited`	This minute's units are used up, or too many wrong keys came from your address.	Wait `Retry-After` seconds, then retry with backoff.	yes
500	`internal`	Something failed on ChartDeck's side.	Retry later; quote the request id to support if it persists.	yes
502	`chart_failed`	The picture could not be drawn from the data this call read.	Retry later; the same data are in the matching /v1/strata route.	yes
502	`upstream`	A source behind this route did not answer.	Retry later.	yes
502	`upstream_error`	A source behind this route answered with an error.	Retry later.	yes
503	`api_disabled`	The API is switched off for maintenance.	Retry after `Retry-After`.	yes
503	`archive_unavailable`	The recorded archive this route reads is not reachable right now.	Retry later.	yes
503	`overloaded`	The API is shedding heavy requests under load (lower tiers first).	Retry after `Retry-After`.	yes
503	`render_busy`	Too many chart pictures are being drawn on this server right now.	Retry after `Retry-After` (seconds).	yes
503	`render_timeout`	Drawing the chart picture took too long.	Retry after `Retry-After`; the next call usually reads the finished picture.	yes
503	`renderer_unavailable`	This server cannot draw pictures right now.	Retry later.	yes
503	`unavailable`	This data is temporarily unavailable.	Retry later.	yes
503	`upstream_busy`	A source is rate-limiting ChartDeck right now.	Retry after `Retry-After`.	yes
503	`upstream_unavailable`	A venue did not answer.	Retry later.	yes
503	`warming_up`	The server just started and is still loading this data.	Retry in a few seconds.	yes