Docs › Errors
Errors
Every error is JSON: {"error": "...", "code": "...", ...}. Errors are never charged.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | INVALID_* / MISSING_* / OUT_OF_RANGE / TOO_MANY_SAMPLES / INVALID_JSON / EMPTY_BODY | The 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. |
| 401 | API_KEY_INVALID / CREDITS_TOKEN_INVALID | The X-Credits-Token header holds an unknown or revoked key. | Check the key (copy it again from the welcome page or your billing portal). |
| 401 | SUBSCRIPTION_ENDED | The 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. |
| 402 | CREDITS_INSUFFICIENT | A prepaid-credits token without enough balance for this route. | Top up the same token, or use a subscription key. |
| 403 | PLAN_ROUTE_NOT_INCLUDED | The 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. |
| 413 | BODY_TOO_LARGE | The request body is too large. | Send a smaller body (split a long range). |
| 429 | QUOTA_EXCEEDED | The key's monthly call quota is used up. | Wait for the reset on the 1st (UTC) or move to a larger plan. |
| 429 | FINANCE_DEMO_EXHAUSTED | Free 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. |
| 429 | PLAN_RATE_LIMITED / RATE_LIMITED | Too 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. |
| 503 | BILLING_UNAVAILABLE / CREDITS_UNAVAILABLE | Metering 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
}