# 錯誤

每個端點都以相同方式失敗：HTTP 狀態碼及一個 JSON 封裝。

```json
{
  "error": {
    "type": "invalid_request",
    "code": "invalid_input",
    "message": "duration must be one of 5, 10.",
    "param": "duration",
    "details": [ { "param": "duration", "message": "duration must be one of 5, 10." } ],
    "request_id": null,
    "doc_url": "https://doitong.com/developers/docs/errors#invalid_input"
  }
}
```

| 欄位 | 意義 |
|---|---|
| `type` | 錯誤的大致類別。依此決定要採取的行動。 |
| `code` | 精確原因，穩定且可供機器讀取。每個代碼下方都有對應章節；`doc_url` 會連結至該章節。 |
| `message` | 人類可讀的說明，可安全地記錄或顯示給開發人員。 |
| `param` | 發生問題的輸入參數或標頭（若有）。 |
| `details` | 對於輸入錯誤，列出找到的每個問題：`[{ "param", "message" }]`。 |
| `request_id` | 相關的請求（若存在）。 |

回傳錯誤的呼叫不會產生任何費用。已接受後才失敗的請求會保留 `failed` 狀態，
在請求物件上帶有 `error: { "type", "code", "message" }`，並自動退款。

## 類型

| 類型 | HTTP 狀態 | 處理方式 |
|---|---|---|
| `invalid_request` | 400, 413 或 422 | 修正請求。重試相同呼叫仍會再次失敗。 |
| `authentication_error` | 401 | 在 `Authorization: Bearer <key>` 中傳送有效金鑰。 |
| `permission_error` | 403 | 使用具有所需 scope 的金鑰。 |
| `not_found` | 404 | 檢查模型 ID 或請求 ID。 |
| `insufficient_credits` | 402 | 為 API 餘額儲值（錯誤中的 `top_up_url`）。 |
| `budget_exceeded` | 402 | 金鑰本身的預算已用盡。最終處理方式：請金鑰擁有者提高預算。 |
| `conflict` | 409 | 資源目前的狀態不允許此呼叫。 |
| `rate_limited` | 429 | 等待 `Retry-After` 秒後再試。 |
| `upstream_error` | 502 | 模型後端失敗。可使用相同的 `Idempotency-Key` 安全重試：作業會再次執行，且不會向你收費。 |
| `service_unavailable` | 503 | API 已暫停或相依服務停止運作。稍後再試。 |
| `internal_error` | 500 | 我們的錯誤。請重試；若持續發生，請提供時間及 `request_id` 聯絡支援。 |

## 代碼

### `invalid_request`

一般格式錯誤的請求（400）。

### `invalid_json`

本文不是有效的 JSON（400）。

### `invalid_body`

本文是有效的 JSON，但不是物件；模型輸入必須是 JSON 物件（400）。

### `body_too_large`

本文大於 16 MB（413）。請上傳大型檔案，改為傳遞其 URL（參閱 [檔案](https://doitong.com/developers/docs/files)）。

### `invalid_parameter`

查詢參數的值錯誤，例如 `limit` 不在 1 到 100 之間、`wait` 不是數字、未知的
`status` 或 `category`，或 `storage` 不是 `permanent` / `temporary`（400）。`param` 會指出該參數。

### `invalid_category`

`GET /openapi.json?category=` 指定了不存在的類別（400）。`GET https://api.doitong.com/v1/categories` 會列出類別。

### `invalid_cursor`

清單呼叫中的 `cursor` 不屬於此清單（400）。請不要使用 cursor 重新開始。

### `invalid_idempotency_key`

`Idempotency-Key` 標頭為空或長度超過 255 個字元（400）。

### `invalid_arguments`

MCP 工具呼叫缺少引數或引數格式錯誤（僅限 MCP）。`param` 會指出該引數。

### `invalid_input`

模型輸入未通過驗證（422）：未知參數（訊息會建議最接近的有效名稱）、缺少必要參數、類型錯誤、
值不在允許的清單或範圍內，或同時提供標準名稱與原生名稱但值不同。`param` 是第一個有問題的參數，
`details` 會列出所有問題參數。不會產生任何費用。

### `unsupported_file`

檔案的類型不受支援（422），例如上傳了不支援的副檔名，或 `content_type` 與副檔名不符。

### `invalid_webhook_url`

`webhook_url` 不是公開的 `https://` URL（422）。私人、區域及純 `http://` 位址會遭拒。

### `missing_api_key`

端點需要 API 金鑰，但未傳送任何金鑰（401）。

### `invalid_api_key`

金鑰不存在、已撤銷或已過期（401）。

### `insufficient_scope`

金鑰缺少此呼叫所需的 scope（403），例如執行作業需要 `models:run`，讀取請求及餘額需要 `models:read`。
請參閱 [驗證](https://doitong.com/developers/docs/authentication#scopes)。

### `account_disabled`

帳戶已關閉或遭停權（403）。其金鑰不再有效。

### `not_found`

路徑不存在（404）。

### `model_not_found`

沒有公開模型具有此 ID（404）。使用 `GET https://api.doitong.com/v1/models` 列出模型。

### `request_not_found`

你的帳戶中不存在具有此 ID 的請求（404）。永遠無法查看其他帳戶的請求。

### `insufficient_credits`

帳戶的 **API 餘額**（API 點數、1,000 API 點數 = $1 — 不是 Doitong 應用程式的點數）不足以支付
此呼叫的價格（402）。回應會在任何費用產生前傳送。錯誤會包含 `top_up_url`；請在
[https://doitong.com/developers/dashboard#balance](https://doitong.com/developers/dashboard#balance) 儲值後重試。

```json
{ "error": { "type": "insufficient_credits", "code": "insufficient_credits",
             "message": "This request costs 560 API credits ($0.56); the API balance is 120 API credits ($0.12). Top up at https://doitong.com/developers/dashboard#balance",
             "top_up_url": "https://doitong.com/developers/dashboard#balance", "doc_url": "https://doitong.com/developers/docs/errors#insufficient_credits" } }
```

### `budget_exceeded`

此呼叫會超出 API 金鑰本身以 API 點數計算的預算（402）。預算由金鑰擁有者設定；在其提高預算前重試無效。

### `conflict`

此呼叫與資源目前的狀態衝突（409）。

### `idempotency_mismatch`

`Idempotency-Key` 已搭配不同本文使用過（409）。新操作請使用新的金鑰。

### `idempotency_in_progress`

目前正在建立使用相同 `Idempotency-Key` 的請求（409）。稍候片刻再試以取得該請求。

### `request_active`

請求仍處於 `queued` 或 `running` 狀態，因此尚無可刪除的檔案（409）。完成後再刪除檔案。

### `not_cancelable`

請求已是 `succeeded` 或 `failed` 狀態，無法取消（409）。

### `rate_limited`

金鑰在目前時間窗內建立了過多請求（429）。請參閱 `X-RateLimit-*` 及 `Retry-After` 標頭。

### `too_many_inflight`

帳戶已有 10 個處於 `queued` 或 `running` 狀態的請求（429）。其中一個完成後再啟動下一個。

### `upstream_error`

模型後端拒絕或無法處理請求（執行作業時為 502，或請求以此代碼結束為 `failed`）。API 點數會
退款。如果後端本身拒絕輸入，呼叫會改以 `422 invalid_input` 及其訊息回傳。

### `upstream_lost`

模型後端不再知道此請求，因此永遠不會有結果返回。請求會以此代碼結束為 `failed`
（類型為 `upstream_error`）並退款。請重新執行。

### `timeout`

請求執行時間超過限制（圖像為 15 分鐘、影片為 60 分鐘、其他為 30 分鐘），因此已停止。請求會以
此代碼結束為 `failed` 並退款。

### `service_unavailable`

API 暫時暫停，或檔案上傳等相依服務停止運作（503）。稍後再試。

### `internal_error`

我們這邊發生問題（500）。請重試；若持續發生，請聯絡支援。

### `charge_failed`

由於內部問題，無法向帳戶收費（500）。請求會標記為 `failed`；不會扣除任何費用。請重試。

### `pricing_unavailable`

尚未設定模型價格，因此目前無法報價或執行（500）。