Getting Started
Errors
A single, predictable error envelope with machine-readable codes and request ids.
Error envelope
Every non-2xx response uses the same JSON envelope:
Response · 400
{
"error": {
"code": "invalid_timeframe",
"message": "Unsupported timeframe \"10m\". Use one of 5m, 15m, 1h, 4h, 1d.",
"status": 400,
"request_id": "req_01JD3ZQ8M4F2K7W9"
}
}| Field | Type | Description |
|---|---|---|
| error.code | string | Stable, machine-readable error code. Branch on this, not on the message. |
| error.message | string | Human-readable explanation. May change; do not parse. |
| error.status | integer | HTTP status code, repeated for convenience. |
| error.request_id | string | Unique id of the request. Include it when contacting support. |
Error codes
| Code | Status | Meaning |
|---|---|---|
| invalid_request | 400 | Invalid request. A parameter is missing or malformed. |
| invalid_asset | 400 | Invalid asset. The asset symbol is not supported. |
| invalid_timeframe | 400 | Invalid timeframe. The timeframe is not one of 5m, 15m, 1h, 4h, 1d. |
| invalid_agent | 400 | Invalid agent. The agent slug is not recognized. |
| unauthorized | 401 | Unauthorized. The API key is missing, malformed or revoked. |
| plan_required | 403 | Plan required. Your plan does not include this endpoint or history depth. |
| not_found | 404 | Not found. The market or resource does not exist. |
| not_settled | 409 | Not settled. The market has not settled yet; settlement data is unavailable. |
| rate_limited | 429 | Rate limited. Too many requests. Retry after the time in the Retry-After header. |
| internal_error | 500 | Internal error. Something went wrong on our side. The request id helps us investigate. |
| index_unavailable | 503 | Index unavailable. Too few price sources responded to compute the index (quorum not met). |
Which errors to retry
| Status | Retry? | Guidance |
|---|---|---|
| 400 | No | Fix the request (asset, timeframe, agent or query parameters). |
| 401 / 403 | No | Check the key, its revocation status and your plan's entitlements. |
| 404 | No | The market or resource does not exist. Market ids are deterministic, so check the format. |
| 409 | Later | not_settled: retry after the window's end time. |
| 429 | Yes | Wait for Retry-After seconds, then retry. |
| 500 / 503 | Yes | Retry with exponential backoff and jitter. |
Request ids
Every response, successful or not, includes an X-Request-Id header, and error bodies repeat it as request_id. Log it alongside failures and include it when you contact [email protected].
See the error code reference for a compact list grouped by HTTP status.
Questions or feedback on the API? [email protected]