開發文件

錯誤處理與重試

請求出錯時回傳對應的 HTTP 狀態碼，回應主體沿用所用協定的錯誤格式。按狀態碼區分「改請求」和「可重試」兩類錯誤，是穩定串接的關鍵。

錯誤格式

OpenAI 相容協定：

json

{
  "error": {
    "message": "用户额度不足, 剩余额度: $0.01",
    "type": "new_api_error",
    "code": "insufficient_user_quota"
  }
}

Anthropic 原生協定：

json

{
  "type": "error",
  "error": { "type": "invalid_request_error", "message": "..." }
}

狀態碼速查

狀態碼	意義	處理方式	可重試
`400`	請求參數錯誤：缺少欄位、格式不符合協定、模型不支援該參數	按 `error.message` 修正請求	否
`401`	API Key 缺失、無效、已刪除或過期	檢查請求標頭和 Key 狀態，見認證	否
`403`	餘額或 Key 額度不足，或該 Key 無權使用此模型	儲值，或調整 Key 的額度與模型限制	否
`404`	路徑不存在，多為 Base URL 寫錯	OpenAI SDK 帶 `/v1`，Anthropic / Gemini SDK 不帶	否
`429`	請求過於頻繁	降低並行，按指數退避重試	是
`500` / `502`	服務暫時異常	稍後重試	是
`503`	該模型暫時沒有可用資源，或模型 ID 不存在	核對模型 ID；確認無誤則稍後重試	是
`504`	處理逾時	重試；生圖任務可按任務 ID 取回結果	是

重試策略

只對 429、5xx 和網路錯誤重試，4xx（除 429）重試也不會成功。推薦指數退避加隨機抖動：

retry.py

import random, time
from openai import OpenAI, APIConnectionError, APIStatusError, RateLimitError

client = OpenAI(api_key="sk-...", base_url="https://api.flyrouter.ai/v1", max_retries=0)

def chat(messages, attempts=5):
    for i in range(attempts):
        try:
            return client.chat.completions.create(model="gpt-6.1-sol", messages=messages)
        except (RateLimitError, APIConnectionError) as e:
            err = e
        except APIStatusError as e:
            if e.status_code < 500:
                raise  # 參數、驗證、餘額問題，重試無用
            err = e
        time.sleep(min(2 ** i, 30) + random.random())
    raise err

官方 OpenAI / Anthropic SDK 預設會自動重試 2 次（針對 429 與 5xx），一般情境直接調大 max_retries 即可，不必自己實作。

逾時設定

大模型首字可能需要幾秒到幾十秒，深度思考時更久。用戶端讀取逾時建議至少 10 分鐘，或使用串流輸出。
影像生成同樣建議 10 分鐘以上的逾時。

計費與失敗請求

請求開始時按預估用量預扣額度，完成後按實際用量多退少補。
回傳錯誤、沒有產生內容的請求會退還預扣額度，不扣費。
串流請求中途斷開時，已生成的部分照常計費。

聯絡支援

問題持續出現時，請聯絡我們，並附上請求時間、模型 ID 和完整的錯誤訊息（不要附帶 API Key）。

錯誤處理與重試

錯誤格式#

狀態碼速查#

重試策略#

逾時設定#