Errors

Every error response is JSON with a consistent envelope:

{
  "error": {
    "code": "missing_param",
    "message": "lat and lon are required",
    "request_id": "770372810e5f2a70"
  }
}

code is a stable machine-readable string (listed below); message is human-readable and may change; request_id matches the X-Request-ID response header.

HTTP status codes

Status	Meaning
`200`	Success.
`400`	Invalid request — missing or malformed parameter.
`401`	Missing, unknown or revoked API key.
`402`	Payment required — no credits left, or free-tier cap reached.
`403`	Request IP not in the key's allowlist, or account suspended.
`404`	Unknown endpoint or sub-resource (e.g. an unknown varga or planet name).
`405`	Wrong HTTP method (compute endpoints are `GET`).
`429`	Rate limit hit — wait for `Retry-After` seconds.
`500`	Internal error — retry with backoff; include `request_id` when reporting.
`503`	Billing/data service temporarily unavailable — retry after a short wait.
`504`	Request exceeded the server deadline — retry once; simplify if it repeats.

Error codes

Each code has its own page with the cause and the fix: Troubleshooting.

Code	Status	Meaning
`missing_param`	400	A required query parameter was not supplied.
`invalid_param`	400	A parameter is malformed (bad date, unknown timezone, out-of-range lat/lon).
`bad_request`	400	Malformed request body or unsupported combination.
`unauthorized`	401	Bearer token missing, unknown, or revoked.
`insufficient_credits`	402	Paid / PAYG account has no credits left — top up or upgrade.
`daily_cap_exceeded`	402	Free tier: the 500-credit daily cap is used up (resets at midnight IST).
`monthly_cap_exceeded`	402	Free tier: the 1,500-credit monthly cap is used up.
`trial_exhausted`	402	Trial credits used up.
`quota_exhausted`	402	Plan quota exhausted and overage is disabled on the account.
`payment_required`	402	Generic payment-required condition (see `message`).
`ip_not_allowed`	403	Request origin IP is not in the key's allowlist.
`account_suspended`	403	Account suspended — contact support.
`forbidden`	403	Authenticated, but not allowed to perform this action.
`not_found`	404	Unknown endpoint or sub-resource.
`method_not_allowed`	405	Wrong HTTP method.
`rate_limited`	429	Too many requests for your plan's per-minute limit.
`data_unavailable`	503	Ephemeris/geo data unavailable for the requested input.
`billing_unavailable`	503	Billing service unreachable — retry shortly.
`internal_error`	500	Unhandled error. Reference `request_id` when reporting.

Rate-limit and credit headers

Every authenticated response carries:

X-RateLimit-Limit: 156        # requests per minute for your plan
X-RateLimit-Remaining: 150
X-RateLimit-Reset: 1789363680 # unix seconds when the window resets
X-Credits-Remaining: 1970
Retry-After: 12               # only on 429

Retry semantics

429: wait Retry-After seconds, then retry.
500 / 503 / 504: retry with exponential backoff (1s, 2s, 4s, 8s — max 5 attempts).
Other 4xx: do not retry — the request is deterministically invalid. Fix the parameters, top up credits, or fix the key/IP.

Request ID

Every response (success or error) includes X-Request-ID (16 hex characters). When reporting an issue, always include it — it lets us pull the exact trace from our logs.

X-Request-ID: 52a520f261d3db37