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