錯誤
每個端點都以相同方式失敗：HTTP 狀態碼及一個 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（參閱 檔案）。
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。
請參閱 驗證。
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 儲值後重試。
{ "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）。