錯誤碼

錯誤碼參考

當 API 請求失敗時，響應會包含一個 HTTP 狀態碼和一個錯誤物件，詳細說明出錯原因。下表列出了所有可能的錯誤碼：

錯誤響應格式

錯誤響應遵循以下結構：

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API Key provided.",
    "type": "error"
  }
}

錯誤處理最佳實踐

實現重試邏輯

並非所有錯誤都應該重試，請參考以下指南：

• 可重試錯誤（429、500、503）： 這些是可能自行恢復的臨時性錯誤。建議實現帶指數退避的自動重試。
• 不可重試錯誤（400、401、403、404）： 這些錯誤表明請求或憑證存在問題。請先修復根本原因再重試。

指數退避策略

重試失敗的請求時，使用指數退避策略以避免對伺服器造成過大壓力：

import time
import random

def make_request_with_retry(func, max_retries=5):
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            if attempt == max_retries - 1:
                raise e

            # 帶隨機抖動的指數退避
            delay = min(2 ** attempt + random.random(), 60)
            print(f"請求失敗，{delay:.1f}秒後重試...（第 {attempt + 1}/{max_retries} 次嘗試）")
            time.sleep(delay)

優雅處理速率限制

如果收到 429 rate_limit_exceeded 錯誤：

1. 遵守 Retry-After 頭： 如果響應包含 Retry-After 頭，請至少等待指定時間後再重試。
2. 降低併發量： 減少並行請求數量，確保在速率限制範圍內。
3. 實現請求佇列： 將請求排隊，以可控的速率依次處理。

記錄錯誤日誌

始終記錄錯誤響應的完整資訊，包括完整的錯誤物件、請求 ID（如有）和時間戳。這些資訊在聯絡支援團隊排查持續性問題時非常重要。

傳送前驗證請求

透過在傳送前驗證請求資料，減少 400 invalid_request 錯誤：

• 確保所有必填欄位都已填寫。
• 確認模型名稱與可用模型之一匹配（mimo-v2-pro、mimo-v2-omni、mimo-v2-tts、mimo-v2-flash）。
• 檢查引數值在可接受範圍內。
• 確認 API Key 已設定且不為空。