錯誤

錯誤一律是 application/problem+json（RFC 9457）。請依 code 分支；detail 是給人看的，可能改寫。

{
  "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。pending 與 ready 只出現在 data_pending。

錯誤碼

代碼	HTTP	意思	該怎麼做
`unauthenticated`	401	金鑰缺少、格式錯誤、過期或已撤銷	修正金鑰；不要原樣重試
`forbidden`	403	金鑰缺少 kind、權限、盤口檔數或 scope	請管理員補上缺少的部分
`not_found`	404	沒有這個路由、商品、匯出或檔案	檢查路徑或代號；匯出過期就重新提交
`invalid_argument`	400	參數缺少、格式錯誤或超出範圍	修正請求；`param` 指出欄位
`ambiguous_symbol`	409	一個拼法在該日對到多個商品	用完整代號或 `instrument_id`
`unsupported_resolution`	400	K 線比資料更細、資料集不支援，或商品沒有歷史	改用較粗週期或別的資料集
`version_unavailable`	410	舊的 `catalog_version` 或 `resume_token` 已不保留	去掉固定版本重查，或重新訂閱
`resource_exhausted`	413 或 429	請求或答案太大，或碰到串流上限	縮小請求；429 依 `retry_after` 重試
`quota_exceeded`	429	每把金鑰的請求、輸出、工作或串流上限已用完	等 `retry_after` 後重試；請管理員調大政策
`data_pending`	503	交易日、匯出檔或前一日還在準備	依 `retry_after` 用同一請求重試
`resync_required`	503	串流用戶端落後，佇列溢出	用最後的 `resume_token` 重連
`unavailable`	503	相依服務或日曆暫時不可用	退避重試
`internal`	500	未預期的伺服器錯誤	重試一次，再回報時間或請求資訊

JSON 內容過大與 MCP 答案過大回 413；串流訂閱超過上限回 429，數字見限制。同一個代碼可能有兩種狀態；請依代碼分支，狀態只用於顯示。

重試

data_pending：用同一請求重試。不要重新建立工作；缺少的 instrument-day 已在佇列中。
unavailable、internal：指數退避加 jitter。
resource_exhausted 且 429：等 retry_after 後重試。
quota_exceeded：等 retry_after；一直碰到代表政策對這個工作量太小。
version_unavailable：不要重試固定版本；去掉 pin 或重新訂閱。
其他：先修正請求或金鑰。

Python SDK 會重試忙碌回應與網路錯誤；PendingTimeout 代表等到 pending_timeout 資料還在準備。

認證與權限

除了 GET /v2/openapi.json，每個 /v2 路由都需要 Authorization: Bearer vmk_...。目錄需要任何有效金鑰。資料需要資料集 kind、 history，快照還需要盤口檔數。即時需要 live；匯出除了資料權限還需要 export。

403 會指出缺少的能力。見 API 金鑰與管理。

錯誤碼​

重試​

認證與權限​

錯誤碼

重試

認證與權限