Claude API 的 429 rate_limit_error——代表什麼以及如何解決

429 的意思是「慢一點」，不是「你沒錢了」。差異很重要：前者的修正方式是等待，後者則是儲值；混淆兩者會讓你花數小時在錯誤的方向除錯。

錯誤

resposta (HTTP 429)

{
  "type": "error",
  "error": { "type": "rate_limit_error",
             "message": "Number of requests has exceeded your rate limit" }
}

原因與解決方法一覽

原因	解決方法
超過帳戶的每分鐘請求限制	在用戶端排入佇列並限制並行數，而不是一次發送所有請求。
超過每分鐘 token 限制	長提示會在請求配額之前就大量消耗 token 配額。請減少上下文或拆分工作。
多個程序使用同一組金鑰	限制是針對金鑰，而非程序。平行 worker 會共同計入同一個配額。
沒有退避的重試	立即重試會讓你持續超過限制。指數退避加上 jitter 是必要做法。

收到 retry-after 時請遵守

當回應包含 retry-after 標頭時，它不是建議，而是請求再次被接受前的確切等待時間。等待更短必然會再次收到 429。

retry_after.py

import time
from openai import APIStatusError

try:
    resp = client.chat.completions.create(model=MODELO, messages=msgs)
except APIStatusError as e:
    if e.status_code == 429:
        espera = float(e.response.headers.get("retry-after", 5))
        time.sleep(espera)
        resp = client.chat.completions.create(model=MODELO, messages=msgs)
    else:
        raise

從源頭限制並行數

最常見的原因不是總量，而是突發流量：同一瞬間發出的 20 個請求會超過限制，而分散在一分鐘內的 60 個請求不會。信號量能解決單靠重試無法解決的問題。

concorrencia.py

import asyncio

LIMITE = asyncio.Semaphore(4)   # no máximo 4 chamadas simultâneas

async def chamar(msgs):
    async with LIMITE:
        return await client.chat.completions.create(
            model=MODELO, messages=msgs)

確認是速率限制，而不是餘額

429 絕不代表點數不足——那是 402。如果您的日誌將兩者混在一起，請先依狀態碼分開，再進行調查：429 的修正方式是調整時序，402 的修正方式是儲值。重試 402 會永遠失敗。

如果你透過 Kunavo 呼叫

在 Kunavo 中，限制依金鑰計算，而餘額是獨立的預付錢包，因此兩種情況會顯示不同的狀態碼：429 表示速率限制，402 表示餘額不足以支付此次呼叫——兩者絕不會互相偽裝。遭拒的請求不會收費。決定每次呼叫從餘額扣除多少的 Token 費率，列於我們的 Claude API 價格指南.

常見問題

429 代表我的點數用完了嗎？

不是。餘額不足是 402。429 與速度有關：您在短時間內傳送了過多請求或 Token，等待即可解決。

我應該等待多久？

如果回應包含 retry-after 標頭，就等待該標頭指定的確切時間。若沒有，請從 1–2 秒開始採用帶有抖動的指數退避，直到 30–60 秒的上限。

提高限制有幫助嗎？

如果流量確實很高，會有幫助；但多數 429 來自短時間的突發流量。限制並行數通常就能解決，不必變更任何限制。