Docs › Errors

Errors

Every error is JSON: {"error": "...", "code": "...", ...}. Errors are never charged.

StatusCodeMeaningWhat to do
400INVALID_* / MISSING_* / OUT_OF_RANGE / TOO_MANY_SAMPLES / INVALID_JSON / EMPTY_BODYThe request is invalid. The body says which field: {error, code, field}.Fix the field named in 'field'. A 400 is never charged and never counted.
401API_KEY_INVALID / CREDITS_TOKEN_INVALIDThe X-Credits-Token header holds an unknown or revoked key.Check the key (copy it again from the welcome page or your billing portal).
401SUBSCRIPTION_ENDEDThe plan behind this key has ended.Subscribe again on /pricing.
402(x402 / MPP offer)No key was sent and the client's free call is used, or the route is not free. The body carries the x402 offer; the WWW-Authenticate header carries the MPP offer.Send your key in X-Credits-Token, or pay this call with x402 or MPP.
402CREDITS_INSUFFICIENTA prepaid-credits token without enough balance for this route.Top up the same token, or use a subscription key.
403PLAN_ROUTE_NOT_INCLUDEDThe Free plan does not include this route.Upgrade to Indie or above, or call a route your plan includes.
404-Unknown path.Check the route in /docs or GET /v1/catalog.
413BODY_TOO_LARGEThe request body is too large.Send a smaller body (split a long range).
429QUOTA_EXCEEDEDThe key's monthly call quota is used up.Wait for the reset on the 1st (UTC) or move to a larger plan.
429FINANCE_DEMO_EXHAUSTEDFree plan: the 100 monthly demo calls to the premium data routes (time series, event calendar, sky search) are used up.Wait for the reset on the 1st (UTC) or upgrade.
429PLAN_RATE_LIMITED / RATE_LIMITEDToo many calls in one minute.Wait for the Retry-After header (seconds), then retry. Nothing was charged.
500-Internal error. Nothing was charged.Retry once; if it persists, write to support.
503BILLING_UNAVAILABLE / CREDITS_UNAVAILABLEMetering is briefly unavailable. Nothing was counted.Retry with a short backoff (1 s, 2 s, 4 s).

Retries

Retry 429 after the Retry-After header and 503 with a short backoff. Do not retry other 4xx statuses unchanged: fix the request or the key first.

Example

{
  "error": "'datetime' must look like 1990-05-15T14:30 or 1990-05-15T14:30:00+02:00",
  "code": "INVALID_DATETIME",
  "field": "datetime",
  "endpoint": "western/positions",
  "charged": false
}