DeepSeek API 503/429 錯誤的重試與熔斷策略

503 與 429 都是暫時性錯誤，但處理方式不同：503 通常表示服務端暫時不可用，429 表示你的請求過快。兩者都需要重試，但不能無腦循環。申請 API 前可先了解密鑰與限流規則。

錯誤區分

503 與 429 錯誤處理流程

狀態碼	含義	是否適合重試
503	服務暫時不可用	是，需退避
429	超出速率限制	是，需更長等待
401/403	認證或權限問題	否，檢查 Key
400	請求格式錯誤	否，修正參數

指數退避重試（Exponential Backoff）

基本流程：

首次失敗後等待 1 秒
第二次等待 2 秒，第三次 4 秒
加入隨機抖動（jitter），避免多個客戶端同時重試
設定 maxRetries = 3 或 5，超過則返回友好錯誤

Python 伪代码示例：

import random, time

def call_with_retry(fn, max_retries=4):
    for attempt in range(max_retries):
        try:
            return fn()
        except TemporaryAPIError as e:
            if attempt == max_retries - 1:
                raise
            wait = (2 ** attempt) + random.uniform(0, 0.5)
            time.sleep(wait)

熔斷器（Circuit Breaker）

連續失敗達到閾值時，暫停請求一段時間，避免把已過載的服務打得更忙。

典型參數：

失敗閾值：5 次連續 503/429
熔斷開啟時間：30–60 秒
半開狀態：允許 1 個探測請求，成功則恢復

429 的特殊處理

優先讀取 Retry-After 回應頭
若無該字段，429 的等待時間應比 503 更長
對批量任務使用隊列 + 固定並發（如同時最多 2 個請求）

用戶端應有的降級方案

返回「服務繁忙，請稍後再試」而非 raw error
對可緩存問題（FAQ、固定模板）使用本地緩存
關鍵流程提供人工兜底入口

排查日誌關鍵字段

記錄以下字段，方便定位是平台高峰還是自己請求模式問題：

HTTP 狀態碼
重試次數與每次等待時間
請求耗時
使用的模型與 Token 數
不要對 401/403 盲目重試，會浪費配額
每次重試記錄 attempt 與 wait_ms 便於事後分析

穩定的重試策略能把暫時性故障對用戶的影響降到最低。離線測試可改用 Ollama 本地部署；網頁版登入問題見登入排查指南。