Anthropic 529 overloaded_error：它的意義與應對方式

當 API 暫時超載時，Claude API 會回傳 529，錯誤類型為 overloaded_error。 根據 Anthropic 的說法，當 API 在所有使用者中流量過高時，就可能發生這種情況。 你的請求沒問題。 API 很忙，所以它拒絕了這個請求。 當你的組織超出自身的費率限制時，你會拿到429。 回應主體的形狀與其他 Claude API 錯誤相同：頂層typeerror為 、一個error具有 type 和 message的物件，以及 request_id a 你可以給 Anthropic 支援。 欲了解更多資訊，請參閱 Claude API 錯誤。

529、429，或是消費上限：如何分辨它們

Claude API 則對截然不同的問題使用外觀相似的錯誤。 有些你等一會兒就消失了。 有一個要到下個月才會消失。

回應 error.type retry-after 這是什麼意思? 怎麼辦？
529 overloaded_error 如果有就用吧 API 對所有使用者皆處於超載狀態 稍後再試幾次
429 rate_limit_error Yes 你的組織超出請求數、輸入代幣或每分鐘輸出代幣數，或是提升速率過快而達到加速限制 等待時間以 retry-after 顯示為準
429 rate_limit_error，設 error.details.error_code 為 enforced_spend_limit_reached No 您的組織已達到使用等級的月支出上限 不要重試。 使用暫停至下個月第一天 00：00 UTC，或直到您升級到更高方案為止。
400 invalid_request_error No 使用量達到你在組織或工作區設定的支出上限 提高或取消限制

spend-cap 429 的錯誤類型與速率限制相同，因此每隔 rate_limit_error 就重試的程式碼都會一直失敗。 Anthropic 指出，在存取恢復前，重試都會失敗，包括 SDK 的自動重試。 詳情請參閱 達到支出上限。

如何處理529

  1. 重試前先檢查狀態碼。 A 529 和 A 429 需要不同的等待方式，而 A 429 沒有 retry-after 則完全不需要重試。
  2. 不要選擇 529。 用指數退避和隨機抖動重試，幾次後停止。 如果回應有 retry-after 標頭，就等那麼久。
  3. 讓 SDK 來做前幾次重試。 官方 Anthropic SDK 預設會重試連線錯誤、速率限制和 5xx 錯誤兩次，採用指數退避，並在存在時遵循 retry-after。 你可以用 max_retries（在 TypeScript 中為 maxRetries）來更改數量。 當 SDK 重試次數用盡時，你的程式碼就會收到該錯誤。
  4. 遇到消費上限時，停止重試。 如果 429 沒有 retry-after 標頭欄位，請告訴使用者並提醒自己。
  5. 隨時讓使用者知道最新狀況。 先將工作排入佇列，稍後再試，或顯示明確的「系統忙碌中，請稍後再試」訊息，而非一般錯誤。

在 Python SDK 中，429 會引發 anthropic.RateLimitError，任何狀態達到 500 或以上（包括 529）會引發 anthropic.InternalServerError：

import anthropic

client = anthropic.Anthropic(max_retries=4)


def summarize(text: str) -> str | None:
    try:
        message = client.messages.create(
            model="claude-sonnet-5",
            max_tokens=1024,
            messages=[{"role": "user", "content": f"Summarize:\n\n{text}"}],
        )
    except anthropic.RateLimitError as e:
        if "retry-after" not in e.response.headers:
            # Spend cap: every retry fails until access resumes
            alert_admin(e)
            return None
        raise
    except anthropic.InternalServerError as e:
        if e.status_code == 529:
            # Overloaded after all SDK retries: queue the job for later
            queue_for_later(text)
            return None
        raise
    return next(block.text for block in message.content if block.type == "text")

如何測試你的應用程式是否能處理 529

你在開發過程中很少看到529。 它依賴每個 Claude API 使用者的流量，所以你無法觸發它。 你測試的方式決定了你是否比使用者先發現錯誤。

Approach 你發現的 你錯過的內容
等待正式環境 實際超載 在使用者觸發之前，一切皆如此
在測試中模擬 API，或讓你的程式設計代理撰寫 mock 不管你的錯誤分支是否執行 Anthropic 的真實狀態碼和錯誤實體，以及你 SDK 的重試政策。 你的應用程式也需要一個僅供測試使用的開關來連到模擬環境。
一直呼叫真正的 API，直到它失敗為止 實際行為 你不能隨需觸發529，也不能安全地觸發消費上限
攔截應用程式的真實流量，並視需要回傳 529 和 429 狀態碼 真實網址、真實的 SDK 與重試政策，以及 Anthropic 自有的錯誤格式 你的應用程式裡沒有什麼改變，所以無法對你的程式碼進行隔離測試。 保留你的單元測試。

試試看你的應用程式

Dev Proxy 會攔截你應用程式對 https://api.anthropic.com 的請求，並以 Anthropic 的錯誤格式回傳錯誤，而你的應用程式則持續呼叫真實網址。 下載一個預設，並用它啟動 Dev Proxy：

devproxy config get anthropic-throttling
devproxy --config-file "~dataFolder/configs/anthropic-throttling/.devproxy/devproxyrc.json"
Preset 它傳回什麼
anthropic-throttling 隨機情況下，4,429 個 rate_limit_error 回應中隨機 1 個（請求、輸入權杖、輸出權杖和加速上限）或 529 overloaded_error。 對於 429 回應時，Dev Proxy 會設定 retry-after，並在你的應用程式再次過早呼叫 API 時通知你。
anthropic-random-errors 隨機選取 Claude API 錯誤清單中的一個錯誤，包含 400、401、402、403、404、409、413、429、500、504 和 529，對 50% 的請求

這兩個預設都沒有包含支出上限的 429。 要測試該路徑，可以在預設集的retry-after檔案中加入一個沒有anthropic-errors.json標頭的回應：

{
  "statusCode": 429,
  "headers": [
    { "name": "content-type", "value": "application/json" }
  ],
  "body": {
    "type": "error",
    "error": {
      "type": "rate_limit_error",
      "message": "You have reached your API usage limits.",
      "details": { "error_code": "enforced_spend_limit_reached" }
    }
  }
}

要讓每個請求都失敗，這樣你就能看到當 SDK 重試用盡時會發生什麼，請用 --failure-rate 100 啟動 Dev Proxy。 欲了解更多資訊，請參閱 變更請求失敗率。 要安裝 Dev Proxy，請參見 設定 Dev Proxy。

下一步

使用隨機錯誤測試我的應用程式

也請參閱

  • Last updated on