> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 錯誤碼

> 錯誤回應的格式與穩定的 code 表。

## 錯誤格式

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

```json theme={null}
{
  "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` 物件。

```json theme={null}
{ "code": "provider_unavailable", "message": "…", "retryable": true }
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.