Errors

Every error response follows a consistent JSON envelope:

{
  "error": {
    "code": "invalid_parameter",
    "message": "`date` must be in ISO 8601 format (YYYY-MM-DD)",
    "field": "date",
    "request_id": "req_01hqy7k8c3e7m1n"
  }
}

HTTP status codes

Status	Meaning
`200`	Success.
`400`	Invalid request (bad parameter, malformed JSON).
`401`	Missing or invalid API key.
`402`	Payment required — trial exhausted or subscription expired.
`403`	IP not allowed by key's allowlist.
`404`	Unknown endpoint or sub-resource (e.g. unknown varga).
`429`	Rate limit hit — check `Retry-After` header.
`500`	Internal server error — retry with exponential backoff.
`503`	Service unavailable — retry after cooldown.

Error codes

Code	Status	Meaning
`invalid_parameter`	400	A query parameter is missing or malformed.
`unauthorized`	401	Bearer token missing or invalid.
`forbidden_ip`	403	Request origin IP not in key's allowlist.
`trial_exhausted`	402	Free trial credits used up.
`subscription_inactive`	402	Plan canceled or payment failed.
`rate_limited`	429	Too many requests. See `Retry-After`.
`unknown_endpoint`	404	Path doesn't match any registered route.
`internal_error`	500	Unhandled error. Reference `request_id` when reporting.

Retry semantics

429: wait the number of seconds in Retry-After before retrying.
5xx: retry with exponential backoff (e.g. 1s, 2s, 4s, 8s, max 5 attempts).
4xx (except 429): do not retry — the request is deterministically invalid.

Request ID

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

X-Request-ID: req_01hqy7k8c3e7m1n