Claude Code が 500、529、またはレート制限のような文言を出したら、最初にやることは連続 retry や plan 変更ではありません。500 は status 確認、繰り返す 529 は過負荷、429 や明確な利用枠文言は制限の確認へ進みます。
特に危ないのは 529 です。Claude Code の説明では、繰り返す 529 は過負荷であり、個人の利用上限ではなく、quota にも数えられません。まず終端の文言を下の表に当ててください。
| 見えている文言 | まず扱う分岐 | 最初の一手 | 同じ path で確認すること | 深掘りする境界 |
|---|---|---|---|---|
500 | サービス側の内部エラー | Claude Status を見て、短く待ち、同じ command を一度だけ再実行 | 同じ command、認証経路、model | status が緑でも同じ path が失敗 |
繰り返す 529 | capacity overload | status を見て待つ。task が許す時だけ /model | 同じ session と経路を短い cool-down 後に確認 | status と経路を見ても繰り返す |
429 | API key または provider の制限 | 待機時間、Console limits、model limits、API 経路を見る | window 後、または経路 correction 後に retry | headers や Console が limits を示す |
Server is temporarily limiting requests、session limit、weekly limit | Claude Code throttle または usage window | cool down、または plan/session window を確認 | window 変化後に同じ workflow を再開 | 文言が plan や reset window を示す |
| plan が想定と違う | route override | /status と ANTHROPIC_API_KEY、proxy を確認 | intended subscription / API-key route を確認 | 正しい route でも同じ分岐で失敗 |
先に分岐し、理屈は後で足す
Claude Code の error reference は、runtime errors を Claude API の code に対応させています。また、Claude Code は一部の transient failures を表示前に自動 retry します。つまり終端に見えている一行は、すでに自動処理が終わった後の判断点です。
最初の問いは「Claude が落ちているのか」でも「自分の quota が尽きたのか」でもありません。その一行がどの document class に属するかです。500 なら status、短い待機、同じ path の一回 retry。繰り返す 529 なら capacity。429 なら API key / provider / model limits。session や weekly limit なら usage window。route が怪しいなら /status を先に見ます。
2026-04-20 の確認時点では、Claude Status は Claude API と Claude Code を operational と表示していました。ただし同日の解決済み incident と 4 月 15 日の Claude.ai / API / Claude Code 関連 incident も履歴にありました。status の文は必ず日付付きで扱い、読者の時点で再確認する必要があります。
500 分岐：status、短い待機、一回だけ同じ command
Anthropic の API error docs は HTTP 500 を api_error に対応させています。Claude Code の error reference でも API Error: 500 Internal server error は infrastructure-side の問題であり、prompt、settings、account が直接原因ではないとされています。
安全な順序は短くできます。
- Claude Status を確認する。
- 少し待ち、同じ command または message を一度だけ retry する。
- 検証中に model、auth route、shell profile、prompt をまとめて変えない。
- incident がなく同じ path がまだ失敗するなら、詳細を保存して
/feedbackまたは support route に進む。
症状が持続する API Error: 500 だけなら、次は Claude Code API Error 500 ガイド です。ここでは 500 を rate limit や 529 と誤処理しないことだけを担当します。
529 分岐：過負荷であって、利用上限ではない
Claude Code docs は繰り返す 529 について明確です。API が全体の capacity pressure を受けており、Claude Code はすでに retry 済みで、529 は利用上限ではなく quota にも数えられません。
最初の一手は upgrade ではありません。
- status に capacity notice がないか見る。
- 数分待ってから試す。
/modelは、task が別 model を許す時だけ使う。- 短い cool-down 後、同じ session と route を確認する。
それでも repeated 529 が戻るなら、Claude Code overloaded error ガイド に進みます。529 overloaded_error と 429 rate_limit_error を同じ扱いにすると、billing、key rotation、plan change に早く寄りすぎます。
レート制限分岐：429、temporary limiting、利用枠を分ける
Claude Code で「制限」と見えるものは少なくとも三つあります。
一つ目は実際の API 429 rate_limit_error です。API key、provider project、model-specific limits、concurrency、retry-after が evidence になります。この場合は Claude Code rate limit ガイド が担当します。
二つ目は Server is temporarily limiting requests (not your usage limit) という temporary limiting です。これは短い throttle として扱い、少し待って同じ path を再確認します。plan が尽きた証拠ではありません。
三つ目は本当の usage window です。session limit、weekly limit、Opus limit、reset time を含む文言なら、/usage、reset timing、plan window を見ます。続きは rate-limit reached ガイド または usage limits 診断 です。
route override 分岐：plan の前に auth を見る
Claude Help は、ANTHROPIC_API_KEY の environment variable が authenticated subscription より優先されること、/status で active auth method を確認できることを説明しています。だから route check は補助ではなく復旧フローです。
secret を出さずに確認します。
- Claude Code で
/statusを実行する。 ANTHROPIC_API_KEYが shell や environment にあるかだけ確認し、key 自体は貼らない。- subscription auth、direct Anthropic API、Bedrock、Vertex、proxy のどれかを確認する。
- 本来使うつもりだった route で同じ request を再実行する。
route を直したら結果が変わる場合、本当の問題は route mismatch です。同じ intended route でまだ同じ分岐が出るなら、support 用の evidence がきれいになります。
エスカレーション前に残す evidence
Anthropic API の error response には top-level request_id が入る場合があり、API response には request-id header があります。Claude Code には /status、/model、/usage、/feedback もあります。
保存するものは短くて十分です。
500、529、429、または limiting message の正確な終端文言- 失敗時刻と timezone
- その時点の Claude Status
/statusで見えた active route- model と
/modelの変更有無 - same-path retry の結果
- request ID または feedback context
分岐を決め、最小動作を行い、同じ path で失敗が残ったら、そこで止めます。無作為な retry は evidence を弱くします。
よくある質問
Claude Code の 529 はレート制限ですか？
いいえ。繰り返す 529 は overload として文書化されています。本当の API rate limiting は 429 rate_limit_error で、temporary limiting と plan-window message も別です。
Claude Code API Error 500 で最初に何をしますか？
Claude Status を確認し、少し待ち、同じ command または message を一度だけ retry します。incident がなく同じ path がまだ落ちるなら、詳細を残して 500 ガイドまたは /feedback に進みます。
Claude Status が緑なのに失敗しますか？
緑の status は live incident を一つ除外するだけです。正確な error、active auth route、model、same-path retry result はまだ確認が必要です。
API key が subscription を上書きしているか確認する方法は？
Claude Code で /status を実行し、shell に ANTHROPIC_API_KEY が設定されているか確認します。key 本体は貼らないでください。
529 を見たら plan を上げるべきですか？
最初の一手としては不要です。繰り返す 529 は overload branch です。upgrade 判断は、明確な plan-limit または usage-window wording の時だけです。