錯誤碼 - Blon

錯誤格式

每個錯誤都是同一個信封：

{
  "error": {
    "code": "insufficient_credits",
    "message": "…",
    "request_id": "req_…",
    "retryable": false,
    "retry_after_seconds": null,
    "details": { "required": "94.50", "available": "40.00", "currency": "CREDITS" }
  }
}

欄位	說明
`code`	穩定的機器可讀代碼，見下表。請依它判斷，不要比對 `message`。
`message`	給人看的說明，內容可能變動。
`request_id`	與 `X-Request-Id` header 相同，回報問題時請附上。
`retryable`	同一個請求之後是否可能成功。
`retry_after_seconds`	有值時，請等待這麼久再重試；`Retry-After` header 同值。
`details`	部分 code 的附加資料，例如 `details.errors` 的驗證錯誤或上例的金額。

Code 表

HTTP	`code`	可重試	說明
400	`bad_request`	否	body 不是有效的 JSON，或 `Idempotency-Key` 等 header 格式錯誤
400	`invalid_input`	否	欄位驗證失敗，見 `details.errors`
400	`unknown_parameter`	否	—
401	`unauthorized`	否	缺少、已撤銷或無法辨識的金鑰，或上傳票券無效
401	`session_not_accepted`	否	—
402	`insufficient_credits`	否	餘額不足以支付估價；儲值後再試
403	`forbidden`	否	呼叫者不能在此工作區操作
403	`spending_disabled`	否	此呼叫者的花費權已關閉
403	`monthly_cap_exceeded`	否	已達每月花費上限
403	`api_key_spend_limit_exceeded`	否	已達金鑰的花費上限
403	`insufficient_scope`	否	金鑰缺少權限，`details.required` 指出所需權限
403	`plan_required`	否	工作區的方案不包含此功能
404	`not_found`	否	找不到工作、執行或資源，或你沒有讀取權限
404	`model_not_found`	否	找不到模型，或未對此呼叫者提供
404	`workspace_not_found`	否	工作區不存在，或金鑰不屬於該工作區
408	`request_timeout`	是	請求逾時
409	`conflict`	否	請求與目前狀態衝突
409	`idempotency_conflict`	否	此 `Idempotency-Key` 已用於內容不同的請求
409	`model_price_unavailable`	否	模型目前沒有可用的價格
409	`job_not_cancelable`	否	只有 `queued` 的工作可以取消
412	`precondition_failed`	否	請求的前提條件不成立
413	`payload_too_large`	否	宣告的上傳大小超過上限
415	`unsupported_media_type`	否	不支援此上傳檔案類型
422	`input_media_unreadable`	否	媒體輸入抓不到、超過上限或無法讀取
429	`queue_full`	是	工作區佇列已滿
429	`concurrency_limit`	是	同時執行的工作過多
429	`rate_limited`	是	請求過於頻繁
500	`internal_error`	是	Blon 端的未預期錯誤
501	`not_implemented`	否	不支援
502	`provider_submission_failed`	否	供應商拒絕了提交
503	`provider_capacity_exceeded`	是	供應商容量已滿
503	`provider_unavailable`	是	供應商暫時無法使用
503	`model_disabled`	是	模型暫停中
503	`service_unavailable`	是	Blon 暫時無法使用

提交時被拒（402、403、429）不收費。

重試

只在 retryable 為 true 時重試。有 retry_after_seconds 時先等待，否則以指數退避。重試 POST /jobs 時請沿用同一個 Idempotency-Key，才不會建立第二筆工作。

工作的錯誤

工作被接受之後才失敗，不是 HTTP 錯誤：GET /jobs/{id} 回 200，status 為 "failed"，並帶 error 物件。

{ "code": "provider_unavailable", "message": "…", "retryable": true }

`error.code`	說明
`content_policy`	供應商拒絕了內容
`invalid_input`	供應商拒絕了某個輸入
`rate_limited`	供應商端被限流
`provider_unavailable`	供應商無法使用
`timeout`	工作超過模型的執行期限
`unknown`	其他失敗