Errors

Errors are application/problem+json (RFC 9457). Branch on code; detail is for humans and may be reworded.

{
  "type": "https://data.cyberun.cloud/docs/errors#invalid_argument",
  "title": "Bad Request",
  "status": 400,
  "code": "invalid_argument",
  "detail": "symbols is 1 to 100 comma-separated symbols",
  "param": "symbols"
}

retry_after is present when the server can estimate a wait. pending and ready are present on data_pending.

Codes

Code	HTTP	Meaning	What to do
unauthenticated	401	Missing, malformed, expired or revoked key	Fix the key; do not retry unchanged
forbidden	403	The key lacks a kind, permission, book depth or scope	Ask the administrator for the missing piece
not_found	404	No such route, instrument, export or file	Check the path or symbol; for an expired export, submit a new job
invalid_argument	400	A parameter is missing, malformed or out of range	Fix the request; param names the field
ambiguous_symbol	409	A spelling names more than one instrument on that day	Use the full symbol or instrument_id
unsupported_resolution	400	The requested bars are finer than the data, the dataset does not support the request, or the instrument has no history	Use a coarser interval or another dataset
version_unavailable	410	An old catalog_version or resume_token is no longer kept	Repeat without the pinned version, or resubscribe
resource_exhausted	413 or 429	The request or answer is too large, or a stream limit was hit	Narrow the request; for 429, retry after retry_after
quota_exceeded	429	A per-key request, output, job or stream limit is used up	Wait retry_after, then retry; ask the administrator for a larger policy
data_pending	503	The trading days, export files or the previous day are still being prepared	Retry with the same request after retry_after
resync_required	503	A stream client fell behind and its queue overflowed	Reconnect with the last resume_token
unavailable	503	A dependency or the calendar is temporarily unavailable	Retry with backoff
internal	500	An unexpected server error	Retry once, then report it with the request id or time

JSON body limits and oversized MCP answers report 413; a stream subscription over its subscription or symbol limit reports 429. The numbers are in Limits. The same code can therefore appear with two statuses; branch on the code and use status only for display.

Retrying

• data_pending: retry the same request. Do not start a new job; the missing instrument-days are already queued.
• unavailable, internal: retry with exponential backoff and jitter.
• resource_exhausted with 429: wait for retry_after, then retry.
• quota_exceeded: wait for retry_after; repeated hits mean the policy is too small for the workload.
• version_unavailable: do not retry the pinned version; drop the pin or resubscribe.
• Everything else: fix the request or the key first.

The Python SDK retries busy answers and network failures; PendingTimeout means it waited pending_timeout and the data was still being prepared.

Authentication and permissions

Every /v2 route except GET /v2/openapi.json needs Authorization: Bearer vmk_.... The catalog needs any valid key. Data needs the dataset kind, history, and a book depth for snapshots. Live needs live; exports need export in addition to the data permissions.

A 403 names the missing capability. See API keys and Administration.