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.
400INVALID_FORMAT / FORMAT_NOT_AVAILABLE'format' is not json or csv, or the route has no table to export as CSV.Use ?format=csv on a tabular route (see /docs/export), or JSON. Never charged.
403PLAN_ROUTE_NOT_INCLUDEDThe Free plan does not include this route.Upgrade to Indie or above, or call a route your plan includes.
401 / 403EXPORT_PLAN_REQUIREDPOST /v1/export without a Pro or Scale key.Send a Pro or Scale key, or page the route yourself (the SDK does it).
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.
429PREMIUM_DEMO_EXHAUSTEDFree plan: the 100 monthly demo calls to the premium data routes (time series, event calendar, sky search, planetary phenomena, local eclipses) 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": "astronomy/positions",
  "charged": false
}