Claude Code や Claude API の呼び出しで API Error: Rate limit reached が出たら、最初に retry を増やすのではなく、どの経路がそのエラーを出したかを確認します。同じ文面でも、Claude Code の利用枠、API key、provider、credits、model/context、または Claude Status の問題で対処が変わります。
| エラーが出た場所 | 先に見るもの | 可能性の高い担当範囲 | 次の動き |
|---|---|---|---|
| Claude Code の terminal / editor | /status、ログイン、plan、ANTHROPIC_API_KEY | Claude Code 利用枠、subscription login、API-key override、context | 同じ session を保ったまま経路を確定し、待機・再ログイン・API 経路の確認へ進む |
| SDK、curl、server log の HTTP 429 | API key、organization、project、model、headers、Console Limits | API の request/token limit、project/model scope | request または token 圧が証明された時だけ backoff する |
| gateway、cloud、provider、hosted app | provider dashboard、upstream body、provider request id | provider quota、wrapper throttle、wrong project、upstream Anthropic limit | direct API の助言を当てる前に provider 側で確認する |
| Console に credits/billing/spend cap が出る | credits、billing、usage、spend cap | アカウント資金または請求状態 | retry を止め、アカウント状態を直す |
| 特定 model や長い context だけ失敗する | model、context size、token volume、concurrency | model family limit または context pressure | context を短くし、output を絞り、小さい model で確認する |
| 複数経路が同時に失敗する | Claude Status、timestamp、request id、recent changes | platform incident または degraded service | 証拠を残し、アカウント変更を急がない |
retry してよいのは、request 数または token 量の圧力が evidence で見えており、reset、header、Console、Rate Limits API、provider のいずれかが待機後の再試行を示している場合だけです。credits、billing、wrong project、wrong key、Claude Code allowance、provider quota、status incident の時は、同じ request を繰り返しても修復にはなりません。
10分で行う復旧順序
まず exact error を保存します。HTTP status、error type、error code、request id、endpoint、model、timestamp、timezone を残してください。Claude Code なら terminal text と /status、API なら response body と headers、provider なら provider request id と upstream body を分けます。
次に active surface を固定します。Claude Code、direct Anthropic API、provider、Bedrock、Vertex、gateway は似た文面を返しても契約が違います。model、key、provider、retry を同時に変えると、成功しても原因が分からなくなります。
三番目に scope を見ます。同じ project の新しい key は project-level limit を直しません。小さい model は billing を直しません。retry loop は Claude Code の usage window を直しません。Console で見ている project と実行環境の project が同じかも確認します。
最後に小さい same-path test を一つだけ実行します。Claude Code なら同じ session で短い command、API なら同じ key と model の小さい request、provider なら同じ provider route の最小 request と log view。目的は branch を証明することです。
API の limit 証拠を正しく読む
Anthropic API の limits は request rate、input tokens、output tokens を分けて扱います。Messages API では RPM、ITPM、OTPM が重要です。request 数が少なくても、長い context や大きな output が token limit に当たることがあります。
API key 経路が確定したら、古い table より現在の evidence を優先します。response headers、retry-after、Console Limits、Usage、Billing、Rate Limits API を確認します。公開記事や社内 runbook に固定の RPM 数を置く場合は、その値が現在の account、project、model、tier から来ているかを明記すべきです。
| evidence | 意味 | 最初の修復 |
|---|---|---|
| headers または Console が request pressure を示す | window 内の request が多い | jitter 付き backoff、concurrency 低下、tenant ごとの queue |
| input/output token pressure が強い | context または generation が大きい | context 短縮、output cap、task split、適切な caching |
| ある model だけ失敗する | model family または選択 model の limit | 小さい model で test、load を下げる、reset を待つ |
backoff は evidence に結びつけます。client が retry-after を返すなら従い、返さないなら exponential backoff with jitter と最大試行回数を設定します。無制限 retry は failed traffic を増やし、障害の所有者を見えにくくします。
Claude Code と API limit を分ける
Claude Code は direct API と同じに見えますが、実際には subscription login、API key override、team env、provider credential のいずれかで動いていることがあります。最初に /status を実行し、現在の session がどの経路かを確認します。
subscription login が active なら、usage、selected model、context size、parallel sessions を見ます。長い coding session では file summaries、tool outputs、過去の context が積み上がります。/compact、新 session、小さい model、parallel session の削減は有効な test になり得ます。ただし、すべての 429 を 1M context のせいにしてはいけません。
API key 経路なら、ANTHROPIC_API_KEY、shell profile、project env、CI variables、provider credentials を確認します。local terminal と remote container が別 key を使うことは珍しくありません。Console で見ている project と実行中の project が違えば、残高や limit が矛盾して見えます。
unsupported token extraction、OAuth workaround、random proxy は使わないでください。経路の証明が難しくなり、secret の扱いも危険になります。安全な選択肢は、待機、load reduction、正しい login、または monitoring できる API route への明示的な切り替えです。
credits、billing、key ownership
credits や billing の問題は、見た目には rate limit と同じく request が止まります。しかし retry は資金や spend cap を直しません。Console が credits、billing、account state の問題を示すなら、request を止めて account state を直します。
key は organization と project に属します。provider route も独自の quota、billing、throttle を持ちます。ticket には key 本体ではなく、organization、project、provider、environment source、deployment environment など安全な識別情報だけを残します。
Claude subscription と API usage は別です。Pro/Max は supported Claude product usage と Claude Code login path に関係しますが、自動的に API credit wallet にはなりません。credits を買う前に、active branch が本当に API funding または billing であることを確認してください。
provider、cloud、status を確認する
Bedrock、Vertex AI、gateway、hosted app、internal proxy は、それぞれ独自の quota、project selection、throttle、model mapping、error wrapping を持ちます。upstream Anthropic error body は有用ですが、direct Anthropic Console が exhausted である証明にはなりません。
provider route では、provider dashboard に quota/billing block があるか、provider log に upstream request id があるか、direct Anthropic credentials でも同じ small request が失敗するかを確認します。これで provider-owned issue、direct API issue、application throttling を分けます。
Claude Status は別の branch です。複数 environment が同時に失敗し、deploy なしに error が増えた時は status を見ます。degraded status は待機を正当化します。green status は個別 key、project、model、provider、Claude Code session の健全性までは証明しません。
support に渡す evidence packet
support には「rate limit reached」だけでは足りません。timestamp と timezone、exact error body、HTTP status、request id、active path、model、endpoint、安全な org/project identifiers、headers、Console/provider limit state、Claude Status state、recent changes を渡します。API key、bearer token、session token、private prompt は含めません。
production では、tenant ごとの queue、model family ごとの concurrency cap、route/project/model/request id/token counts の logging を入れます。Claude Code の team では、session が subscription-authenticated か API-key-authenticated かを記録します。provider では provider id と upstream id を両方保存します。
目的は limit をゼロにすることではありません。どの経路が止まり、どの evidence がそれを示し、retry が安全か、誰が状態を変えるべきかをすぐ判断できることです。
よくある質問
すぐ retry してよいですか？
request または token pressure が証明され、reset、header、Console、provider signal がある時だけです。credits、billing、wrong project、wrong key、Claude Code allowance、provider quota、status incident では retry を止めます。
Pro/Max なのに Claude Code が limit を出すのはなぜですか？
Claude Code は subscription login または API key route で動きます。/status と ANTHROPIC_API_KEY を確認してください。subscription が direct API credits を意味するわけではありません。
API credits を買えば直りますか？
active branch が API funding または billing なら役立ちます。それ以外、たとえば Claude Code usage window、wrong login、provider quota、long context、platform incident には効きません。
長い context や 1M context が原因ですか？
原因になり得ますが、一つの branch です。model、context length、token volume、concurrency、小さい model の test で確認してください。
provider 経由だけ失敗する場合は？
provider dashboard と logs を見ます。provider は別 quota、project、billing、throttle、model mapping を持つことがあります。upstream request id があれば provider id と一緒に保存します。
support には何を送りますか？
timestamp、timezone、exact error body、HTTP status、request id、active path、model、endpoint、安全な org/project identifiers、headers、Console/provider state、status state、recent changes を送ります。secrets は送らないでください。
