Errors

Every failure returns one JSON object with a stable shape, an explicit retryable boolean, and, where a fix exists, a machine-executable way out. This is a real rejection from the live gateway, unedited:

{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid request parameter.",
    "retryable": false,
    "request_id": "ea6d8656-b925-45b9-89c3-65358cad170e",
    "details": {
      "parameter": "tier",
      "given": "prices_only",
      "allowed": ["core", "listed_token", "contract_token"],
      "conflicts_with": "plane"
    },
    "recovery": { "op": "coverage", "params": { "plane": "crypto", "limit": "5" } }
  }
}

retryable: false means the same request will never succeed; fix it instead. details names the exact parameter, what you sent, and what was allowed. recovery is a corrected call an agent can execute verbatim. request_id is safe to share with support. Error responses never charge data credits, though they do spend a rate unit.

Gateway codes

HTTP	Code	Retryable	Meaning
400	`invalid_parameter`	No	No valid request can be formed from the parameters
401	`unauthenticated`	No	Personal key missing or invalid
402	`quota_exhausted`	No	Data credits cannot cover the call’s reserved maximum; `details.credits_remaining` reports your actual remaining balance
409	`idempotency_conflict`	No	An idempotency key was reused for a different request
409	`request_in_progress`	Yes	A duplicate request is already in flight
429	`rate_limited`	Yes	Rate admission denied
500	`internal_error`	No	An unclassified server failure
503	`upstream_unavailable`	Yes	A required boundary is unavailable
504	`timeout`	Yes	No valid response before the deadline

The table reflects current gateway behavior; the retryable boolean in the payload is always the authority.

Data-shaped codes

The engine also refuses at the level of the question itself. These arrive in the same envelope; branch on the retryable boolean the payload carries.

HTTP	Code	Meaning
400	`unsupported_for_asset`	The operation does not exist for this asset (no perp market, wrong class)
400	`plane_mismatch`	An equity operation on a crypto ID, or the reverse
404	`unknown_asset`	Valid grammar, but no such asset in coverage
409	`ambiguous_asset`	The input matches more than one identity; `resolve` it first
413	`response_too_large`	The response would exceed the size bound; narrow the request
422	`insufficient_history`	Not enough history to compute what was asked
403	`forbidden`	The key is valid but not allowed this operation
503	`auth_unavailable`	Authentication cannot be verified right now

A whole operation that cannot prove its primary answer errors like this rather than returning a hollow success. Partial gaps inside an otherwise provable response use the unavailable block instead; that split is defined in the data contract.

What to do

Fix the request for the non-retryable codes: correct parameters against schema, resolve ambiguous symbols, check the key, fund the balance. Retry the retryable codes with backoff, honoring Retry-After where it is sent. Reusing the same idempotency key on those retries is safe: any transient 408, 425, 429, or 5xx releases the idempotency hold, so the retry executes fresh and settles once. internal_error is deliberately not marked retryable because success is not expected; a retry is safe but not promising, so capture the request_id instead.

Deadlines and limits

The gateway uses a 15-second upstream deadline and a 2 MiB response limit. A request that exceeds the deadline returns timeout. When a response would be too large for the service to serve, response_too_large says so; narrow the request with limit, fewer statements, or a shorter range.

Using the API

Guides

Operations

MCP

Gateway codes

Data-shaped codes

What to do

Deadlines and limits

​Gateway codes

​Data-shaped codes

​What to do

​Deadlines and limits

Gateway codes

Data-shaped codes

What to do

Deadlines and limits