Getting started
Errors
One error shape for every endpoint, and what each status means.
Error shape
All errors share one shape:
{"error": {"code": "invalid_api_key", "message": "missing or invalid X-API-Key"}}Status codes
| Status | Code | When |
|---|---|---|
| 400 | bad_request | A parameter is malformed |
| 401 | invalid_api_key | Missing or unknown key |
| 402 | tokens_exhausted | Allowance and top-up used up |
| 403 | demo_not_allowed | The demo key asked for /usage |
| 403 | plan_required | The key's plan does not include this; see below |
| 404 | unknown_event | No such event_id (finished, withdrawn or never listed) |
| 429 | rate_limited | Over the per-key rate; see Retry-After |
| 503 | unavailable | Temporary; retry after Retry-After |
plan_required
A request outside the key's plan answers 403 plan_required before any token is charged. The demo key is on the Free plan, so it gets this on /history, /clv, /racing/history, the WebSocket, tier=extended, finished events and races outside the next 3.
{"error": {"code": "plan_required", "message": "price history needs the Business plan (this key is on Free)",
"plan": "free", "plan_name": "Free", "required_plan": "plus",
"required_plan_name": "Business", "feature": "history"}}plan and required_plan are stable ids (free, core, plus, max); plan_name and required_plan_name are what to show a person (Free, Developer, Business, Enterprise). Do not retry: upgrade the plan or drop the feature.
Retrying
429and503: waitRetry-Afterseconds, then retry.404 unknown_event: the event has left the list. Drop it; it is not charged.400,401,403: fix the request; retrying the same one fails the same way.