跳到內容

錯誤與重試

業務錯誤在回應體頂層返回 code 和 message。detail 多數時候與 message 相同,但也可能是另一段較短的說明(如下例),展示給用戶時以 message 為準:

{
"code": "CONCURRENCY_LIMITED",
"message": "排队中的文件已达上限(1000 个),请等部分文件翻译完成后再提交",
"detail": "排队文件完成一部分后可继续提交"
}

少數業務錯誤只返回 code。參數校驗失敗返回 422,detail 為欄位錯誤列表:

{
"detail": [
{ "loc": ["body", "target_lang"], "msg": "Field required", "type": "missing" }
]
}

請先按 HTTP 狀態處理錯誤,再看 code:許多錯誤只返回通用的 UNKNOWN_ERROR,只有部分錯誤帶有具體的 code(如下文 429 的幾種)。請記錄回應標頭中的 X-Request-Id 以便排查。

狀態含義建議
400請求無效,例如所選配置目前無法使用修正請求,請勿重試
401憑證缺失、無效、過期或已撤銷更換憑證
402餘額(已扣除欠款)未高於任務門檻,或餘額為負;使用 API Key 時也可能是該 Key 的剩餘額度不足充值(或調高 Key 項額)後重新提交
403Key 的限制不允许本次操作(如所選翻譯配置不在允許範圍內)、帳號已停用,或該操作需要登入網頁才能完成(如管理 API Key)檢查 Key 設定,或登入網頁操作
404資源不存在、已刪除或不屬於目前帳號(三種情況的回應相同)核對 ID
409冪等鍵已用於不同請求,或資源目前的狀態不允許執行該操作查詢原始操作後再決定
410資源或介面已永久失效,例如已下線的介面、幂等鍵對應的任務已刪除不要重試
413檔案或請求體超出上限減小檔案
415檔案格式不支援更換格式
422參數驗證失敗,或檔案為空、沒有可處理的內容請按欄位修正,不要自動重試
429頻率、佇列數量或預算受限見下文
5xx暫時性服務錯誤指數退避,設定最大次數
code含義處理
RATE_LIMITED請求過於頻繁請按 Retry-After 等待後重試
CONCURRENCY_LIMITED排隊中的文件翻譯任務已達上限按 Retry-After 等待,或等部分任務完成
AUTH_API_KEY_QUOTA_EXCEEDED該 Key 的預算已用盡在提高預算之前請勿重試

沒有 Retry-After 的 429,請按指數退避處理。

  • 查詢類請求可以直接重試。
  • 建立類別請求重試時,沿用同一個 Idempotency-Key 和完全相同的請求體;每次新的提交使用新的鍵。
  • 上傳失敗時重新申請上傳位址。
  • 為每次請求設定連線、讀取和總超時時間,重試時加入隨機抖動,並限制最大次數。
import random
import time
for attempt in range(5):
response = call_api()
if response.status_code not in {429, 500, 502, 503, 504}:
break
if response.status_code == 429 and response.json().get("code") == "AUTH_API_KEY_QUOTA_EXCEEDED":
break
retry_after = response.headers.get("Retry-After")
delay = float(retry_after) if retry_after else min(2 ** attempt, 16)
time.sleep(delay + random.random())