Developer guide
錯誤代碼
按狀態碼處理及重試規則
閘道器會在上游返回 4xx·5xx 時原樣傳遞該代碼，其他情況則遵循下表的規則。
400·401·403·404·413 是需要修正要求或設定的代碼，而 409·429·5xx 則是用戶端等待後重新發送相同要求的代碼。
錯誤本文的格式因規格而異，而 Anthropic 相容路徑的 error.type 由狀態碼決定。
403 的原因透過 error.message 區分，限額及用量數值可在主控台畫面確認。
狀態碼
| 代碼 | 含義 | 處理方式 |
|---|---|---|
| 400 | 請求值無效。Anthropic 相容模型清單的 limit 超出 1~1000，或嘗試透過 GET /responses/{responseId}?stream=true 以串流方式繼續接收已儲存的回應。 | 請將值修正至有效範圍內。請在不使用 stream 的情況下查詢已儲存的回應。 |
| 401 | 金鑰不存在，或金鑰已過期或撤銷。 | 請在 API 金鑰頁面確認金鑰狀態，並檢查標頭名稱及 Bearer 前綴。 |
| 403 | 沒有模型存取權限、超出使用上限、積分不足，或不是語音的擁有者。 | 請透過 error.message 確認原因，並在下方「限制與使用量確認」一節的畫面中查看數值。 |
| 404 | 模型不存在，或此金鑰無法存取該模型（包括已停止支援的模型）。如果呼叫了不存在的路徑，或要求保留期已過 3 日的 CleviDrive 產出物，也會返回此錯誤。 | 請先使用 GET /models 確認可呼叫的模型清單。請將路徑與「呼叫 API」頁面的表格進行比對。 |
| 408 · 409 · 413 | 上游逾時、擁塞或請求大小超出上限。語音及 voice 路徑的逾時限制為 5 分鐘，請求上限為 28 MiB。 | 如果 409 回應包含 Retry-After，請等待指定時間後重新傳送相同請求。413 則請分拆請求後傳送。 |
| 429 | 上游提供者套用了速率限制。 | 如果有 Retry-After，請等待指定時間後重試；如果沒有，請使用指數退避重試。 |
| 5xx | 閘道或上游發生暫時性錯誤（包括 503）。 | 請使用指數退避重試。如問題持續，請聯絡我們。 |
不會返回 402。積分不足及超出使用上限均會返回 403。
重試及聯絡我們
閘道不會自行產生 429，也不會代替上游回應進行重試或將其加入佇列。等待及重試由用戶端執行。
聯絡我們時，請透過「說明及聯絡我們」提供資料，並附上 X-Request-Id。如果沒有傳送 X-Request-Id，伺服器發出的值會位於 Anthropic 相容回應的 request-id 標頭中。
錯誤本文
錯誤本文的格式因規格而異。上游錯誤只會保留訊息並整理後傳送，不會傳送堆疊或內部欄位。
OpenAI 相容路徑的錯誤本文。
{
"error": {
"message": "API key is required.",
"type": "invalid_request_error"
}
}Anthropic 相容路徑的錯誤本文。error.type 會根據狀態碼按下表設定。
{
"type": "error",
"error": {
"type": "authentication_error",
"message": "..."
},
"request_id": "rqid..."
}| 狀態碼 | error.type |
|---|---|
| 400 | invalid_request_error |
| 401 | authentication_error |
| 403 | permission_error |
| 404 | not_found_error |
| 413 | request_too_large |
| 429 | rate_limit_error |
| 529 | overloaded_error |
| 其他代碼 | api_error |
查看限額及用量
限額數值因工作區而異。請先透過 error.message 確認 403 的原因，然後在以下畫面查看數值。
| 要查看的項目 | 主控台畫面 |
|---|---|
| 套用於工作區的限額 | 概覽中的已分配用量限額 |
| 方案允許的範圍及餘額 | 方案及點數 |
| 實際用量（按模型及金鑰劃分的呼叫量、預計扣減的點數） | 用量 |
| 金鑰狀態（是否已過期或撤銷） | API 金鑰 |