Claude API 的 429 表示你跨越了 Anthropic 的每分鐘限制之一——請求數、輸入 token 或輸出 token。修正方式很少只是「等待更久」：你需要遵守 retry-after、加入帶抖動的退避，並平滑流量突發。以下是完整操作指南。
錯誤
{
"type": "error",
"error": {
"type": "rate_limit_error",
"message": "Number of request tokens has exceeded your per-minute rate limit"
}
}原因與解決方法一覽
| 原因 | 解決方法 |
|---|---|
| 達到每分鐘請求數（RPM）限制 | 在用戶端將請求排入佇列；重試前遵守 retry-after 標頭。 |
| 達到每分鐘輸入 token（ITPM）限制——提示很大、請求很少 | 精簡擷取的上下文；在支援的方案中啟用提示快取，讓快取 token 不再計入限制。 |
| 達到每分鐘輸出 token（OTPM）限制 | 實際設定 max_tokens——對長篇生成而言，OTPM 通常是第一個瓶頸。 |
| 流量突發（cron 在 :00 一次觸發所有工作） | 為排程加入抖動；將批次工作分散到整分鐘內。 |
重試前先讀取回應
Anthropic 會回傳 retry-after 標頭，告知需要等待的秒數，錯誤訊息也會指出你跨越了哪項限制。不讀取它就立即重試，正是讓單一 429 變成 429 風暴的原因。
加入帶抖動的指數退避
只重試可重試的狀態（429、500、529），絕不要重試驗證或驗證錯誤。這段程式碼可原樣用於直接連線 Anthropic 或任何相容 OpenAI 的端點：
import time, random
from openai import OpenAI, APIStatusError
client = OpenAI(base_url="https://api.kunavo.com/v1", api_key="sk-kn-...")
def with_backoff(fn, max_retries=5):
for attempt in range(max_retries):
try:
return fn()
except APIStatusError as e:
if e.status_code not in (429, 500, 529):
raise # don't retry auth/validation errors
retry_after = e.response.headers.get("retry-after")
delay = float(retry_after) if retry_after else min(2 ** attempt, 30)
time.sleep(delay + random.uniform(0, 0.5)) # jitter avoids herds
raise RuntimeError("retries exhausted")
resp = with_backoff(lambda: client.chat.completions.create(
model="claude-sonnet-5",
messages=[{"role": "user", "content": "ping"}],
max_tokens=32,
))
print(resp.choices[0].message.content)減少 token，而不只是減少請求
如果訊息指出是 token 限制，單靠退避無法解決。減少擷取的區塊、限制 max_tokens，並啟用提示快取——在相同輸入模式下，穩定的大型系統提示即使只以 10% 的輸入頻率傳送，也能減輕 ITPM 壓力。
如果你透過 Kunavo 呼叫
透過 Kunavo 呼叫 Claude 不會神奇地消除速率限制，但會改變失敗的成本：失敗請求（包括 429）一律不收費，而且每個金鑰的使用量儀表板會明確顯示是哪個金鑰和模型產生突發流量，讓你能加以平滑。上面的退避程式碼可直接使用——只有 base_url 不同。 速率限制是吞吐量上限，不是價格——若要了解 Claude 實際每 1M token 的費用，以及 Anthropic 官方價目表與我們的價格對照，請參閱 Anthropic Claude API 價格表.
常見問題
升級 Anthropic 使用層級能消除 429 嗎？
較高層級會提高每分鐘上限，因此 429 會較少發生，但任何固定上限都可能被突發流量觸及。無論方案層級為何，正式環境程式都需要退避。
我應該立即重試 429 嗎？
不要——請遵守 retry-after 標頭（若缺少，則使用帶抖動的指數退避）。立即重試會延長受限期間，並可能升級成更長的鎖定。
失敗的 429 請求要付費嗎？
Anthropic 不會對遭拒的請求收費，Kunavo 也不會——失敗請求一律不收費。429 的成本是延遲，而不是金錢。