Errors & rate limits

Every non-2xx response from /v1/... is a JSON object, checked in the order below — the first failing check wins. The 401/403 rows only apply to the key-gated exchange_ohlcv/aggregated_ohlcv endpoints — the public Universe endpoints can only ever return 404 or 422, since there's no key or plan to check. The one status that never comes from the API itself is 429, covered under Rate limits.

Error shape

Most errors return { "detail": "<message>" }. The one exception is 422, FastAPI's own request-validation error, which returns a detail array — see below.

Status codes

Status	Trigger	detail
401	X-API-Key header is missing.	`missing X-API-Key header`
401	The key doesn't exist, or has been revoked.	`invalid or revoked API key`
403	The account has no active subscription.	`no active subscription`
403	Your plan doesn't include this endpoint at all.	`your plan does not include the 'exchange_ohlcv' endpoint`
403	Your plan includes the endpoint, but not this interval.	`your plan does not include interval '4h' for 'exchange_ohlcv'`
403	start is further back than your plan's history depth for this endpoint/interval.	`start=2020-01-01T00:00:00+00:00 exceeds your plan's 30-day history depth for exchange_ohlcv/1h`
404	exchange, interval, base, quote, or method doesn't resolve to a known value.	`unknown exchange: 'binanceX'`
422	A query parameter fails FastAPI's own validation — e.g. limit outside 1–1000, or a malformed start/end.	`see below`

A 422 validation error body:

{
  "detail": [
    {
      "type": "less_than_equal",
      "loc": ["query", "limit"],
      "msg": "Input should be less than or equal to 1000",
      "input": "5000"
    }
  ]
}

Rate limits

There is no call quota: your plan caps what you can query, not how much. Access is governed by two things:

Permissions — which endpoints and intervals your plan allows, and how far back start can reach for each. See Authentication.
10 requests per second — a burst limit enforced at the edge by Cloudflare, before a request reaches the API. Requests above it get 429 Too Many Requests. That response comes from Cloudflare, not the API, so it doesn't follow the JSON error shape above. Wait a moment and retry.

Your call count isn't exposed through /v1 yet — check it from your account's dashboard.

What counts as a call

A request rejected by an auth or permission check — every 401 and 403 above — is never logged against your usage, and a 429 never reaches the API at all. A 404 is different: by the time an unknown exchange/interval/base/quote/method is discovered, your call has already passed every check and reached the database, so it's logged like a normal call. This whole notion of a "logged call" only applies to exchange_ohlcv/aggregated_ohlcv — the public Universe endpoints aren't metered at all, so nothing about them is ever logged.