Claude Codeの429エラー(Rate Limit)、使用量制限との違いを公式ドキュメントで切り分けた
Claude Codeで429エラーが出ても、それはプランの月内制限とは別物。使用量制限・APIレート制限・529オーバーロードの違いを公式ドキュメントで整理し、原因別の対処法とヘッダー活用法をまとめた。
エンジニアのゆとです。
納品前日、案件の仕上げでサブエージェントを何個か並列で走らせてテスト直しをやらせてたら、急にAPI Error: Request rejected (429)って出て止まった。てっきり「またセッション上限か」と思って/usageを叩いたら、そっちは全然余裕がある。じゃあこの429は何なんだ、と公式ドキュメントを漁る羽目になった。
結論から言うと、429は「プランの使用量が尽きた」わけじゃない。プロバイダ側（APIキー、Bedrock、Vertex）に設定されてるレート制限に、瞬間的に触れただけのエラーだ。この記事で以前扱った「使用量制限」とは仕組みがまったく別物で、混同すると変な対処に走ることになる。
公式のエラーリファレンスとレート制限ページを読み込んで、429の正体・自分のケースがどのパターンか切り分ける方法・原因別の対処法をまとめた。
429は「制限」の一種でしかない。まず3つを区別する
Claude Codeを使ってて処理が止まる原因は、実は3種類ある。エラーメッセージがどれも似た空気を出すので混同しやすいが、原因も対処法も別物だ。
| 種類 | 正体 | 出るメッセージの例 | 対処の方向性 |
|---|---|---|---|
| セッション/週次の使用量制限 | プラン（Pro/Max/Team）の会話予算切れ | You've hit your session limit You've hit your weekly limit | リセット時刻まで待つか、プランを見直す |
| 429 レート制限 | APIキー・Bedrockプロジェクト・GCPプロジェクトに設定された「1分あたり」の上限超過 | API Error: Request rejected (429) · this may be a temporary capacity issue. | 秒〜分単位で自然に解消。頻発するなら並列数やティアを見直す |
| 529 オーバーロード | Anthropic側の全体的な高負荷。自分のアカウントの問題ではない | Overloaded | 待つ以外に手がない。ステータスページを確認 |
このうち429だけが「自分の設定・使い方次第で頻度を減らせる」対象になる。529は運要素が強く、以前ここで書いた通り待つしかない。
公式のエラーリファレンスでも、429はrate_limit_errorというタイプ名で明確に区別されていて、「アカウントがレート制限に触れた」とだけ説明されている。プランの月内予算とは管理してる場所そのものが違う。
まず/statusで「どの認証経路を使ってるか」を確認する
429が出たら最初にやるべきは、原因の推測より先に、自分がどの認証経路でリクエストを送ってるかの確認だ。
/statusこれでアクティブな認証情報が表示される。ここで一番ハマりやすいのが、サブスク（claude.aiログイン）で使ってるつもりが、環境変数に残ったANTHROPIC_API_KEYのせいで低ティアのAPIキー経由になっているケースだ。direnvやdotenv系プラグイン、IDEのターミナル設定が.envから古いキーを読み込んでしまうことがある。
# 意図しないキーが残っていないか確認
env | grep ANTHROPICこれは以前書いた「勝手に従量課金になる」問題と根っこが同じで、優先順位の仕組みを知らないと気づきにくい。サブスク契約してるのに429が妙に早く出るなら、まずここを疑ったほうがいい。
サブスク(Pro/Max)ログインで429が出るケース
claude.aiのサブスクでログインしてる場合も、サーバー側の一時的なスロットル（throttle）として429が返ってくることがある。これはプランのクォータを消費するものではなく、公式ドキュメントでは「クォータのヘッダーを持たない一時的な429」と説明されている。
ここでバージョンによる挙動差があるのが厄介なところで、v2.1.199以降ならこの手の一時的な429はAPIキー・Enterpriseだけでなくサブスクログインでも自動的にリトライされるようになった(デフォルトで指数バックオフ、最大10回)。それより前のバージョンだと、サブスクログインでは自動リトライの対象外だったので、目の前で処理が止まって見える。
古いバージョンのまま使ってて429が頻発するなら、まずアップデートを疑うのが早い。
claude update
claude --versionAPIキー(従量課金)で429が出るケース — Usage Tierの壁
ここが一番ボリュームゾーンだと思う。ANTHROPIC_API_KEYを直接使ってる、あるいはpay-as-you-goで運用してるケースだ。
Anthropic APIのレート制限は、Start/Build/Scale(+Custom)というUsage Tierごとに、モデル単位でRPM(1分あたりリクエスト数)・ITPM(1分あたり入力トークン数)・OTPM(1分あたり出力トークン数)の3種類が設定されている仕組みだ。組織は利用実績とアカウントの状態に応じて自動的にティアが上がっていく。新規組織や利用履歴が浅い組織は、標準ティアより低いEvaluation Tierからスタートすることもある。
公式ドキュメント記載のStartティアの目安はこんな感じだ(執筆時点、モデルによって変動する)。
| モデル系統 | RPM | ITPM | OTPM |
|---|---|---|---|
| Claude Sonnet系 | 1,000 | 2,000,000 | 400,000 |
| Claude Opus系 | 1,000 | 2,000,000 | 400,000 |
| Claude Haiku 4.5 | 1,000 | 2,000,000 | 400,000 |
数字だけ見ると余裕そうに見えるが、ここには2つの罠がある。
1つ目は、この制限が「トークンバケット方式」で動いていること。1分あたりの上限が均等に配られてるわけじゃなく、短い時間に集中してリクエストを送ると、平均は上限内でもバーストで引っかかる。公式も「60RPMの制限が1秒1リクエストとして運用されることがある」と明言している。
2つ目は「acceleration limit」の存在だ。組織の利用量が急増すると、ティア上の上限に達していなくても429が返ることがある。トラフィックは急に増やさず、なだらかに増やすのが公式の推奨になっている。バッチ処理を組んでるなら、いきなり全件投げるんじゃなくて、負荷を時間帯でならしたほうが429を踏みにくい。
Claude CodeがRPM/ITPMを早く消費する理由
Claude Code単体のチャット利用と比べて、なぜエージェント運用だと429に当たりやすいのか。原因は「1回の作業に複数のAPIリクエストが積み重なる」構造にある。
サブエージェント(Task tool)を並列で走らせるワークフローは、その分だけ同時にリクエストが飛ぶのでRPMを一気に消費する。ファイル読み込み・grep・コード生成を繰り返す通常の作業でも、コンテキストが長くなるほど1リクエストあたりのITPM消費が増える。
公式ドキュメントが用意してる緩和策はこの3つ。
CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY環境変数で同時実行数を下げる- 並列サブエージェントの数を絞る
- スクリプト実行用途なら
/modelで軽いモデルに切り替える
もう1つ、地味に効くのがプロンプトキャッシュだ。ITPMの計算では、多くのモデルでキャッシュから読んだトークン(cache_read_input_tokens)はカウント対象外になる。公式の例だと、ITPM上限2,000,000でキャッシュヒット率80%なら、実質的に1分あたり1,000万トークン相当を処理できる計算になる。CLAUDE.mdや大きめのコンテキストを毎回素の入力として送ってると、この恩恵を受けられずに早めに天井に当たる。
大量タスクを回すなら、そもそもリアルタイムのMessages APIじゃなくBatch APIに逃がす選択肢もある。処理を非同期化できるタスクなら、コスト削減と一緒にレート制限からも距離を置ける。
Bedrock / Vertex経由の429は別の仕組み
AWS BedrockやGoogle Cloud Vertex AI経由でClaude Codeを使ってる場合、レート制限の管理主体はAnthropicではなく各クラウドプロバイダになる。エラーメッセージの末尾も、Anthropic APIならstatus.claude.comを案内するのに対し、Bedrock/Vertex/Microsoft Foundryならそのプロバイダ自身のステータスページを案内する内容に変わる。
Bedrock特有の話として、Claude 4系モデルには「Token Burndown Rate」という独自の消費計算があり、単純なトークン数だけでなくモデルの処理特性を加味してクォータが減っていく仕組みが報告されている。Anthropic直APIの感覚でティアを見積もると足りなくなることがあるので、Bedrock/Vertexで頻発する場合はAWS/GCPコンソール側のクォータ画面を直接確認したほうが早い。数値は各コンソールでリアルタイムに変わるので、この記事には書かない。
レスポンスヘッダーで先回りする
429が返ってから慌てるより、レスポンスヘッダーを見て「あとどれくらい余裕があるか」を先読みする方法もある。API経由でスクリプトを組んでるなら特に有効だ。
| ヘッダー | 内容 |
|---|---|
retry-after | 再試行までに待つべき秒数 |
anthropic-ratelimit-requests-remaining | 残りリクエスト数 |
anthropic-ratelimit-input-tokens-remaining | 残り入力トークン数(千単位で丸め) |
anthropic-ratelimit-output-tokens-remaining | 残り出力トークン数(千単位で丸め) |
anthropic-ratelimit-tokens-reset | 上限が完全に回復する時刻(RFC 3339) |
自作の自動化スクリプトでClaude APIを叩いてるなら、remainingが閾値を下回った時点で意図的に一呼吸置くロジックを入れておくと、429そのものを踏まずに済む。Claude Code本体を使ってる分にはここまで意識する必要はないが、CI/CDやバッチ処理に組み込んでるなら効いてくる。
対処法まとめ
症状別に、まず何を確認すればいいかを整理するとこうなる。
/statusでアクティブな認証情報を確認し、意図しないANTHROPIC_API_KEYが割り込んでないか見る- サブスクログインなら
claude updateでv2.1.199以降になっているか確認する(自動リトライの対象が広がる) - APIキー運用ならClaude Consoleで現在のUsage Tierと残量を確認する
- サブエージェントの並列数を
CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCYで絞る、または並列実行そのものを減らす - CLAUDE.mdや大きい固定コンテキストはプロンプトキャッシュが効く構成にする
- 大量タスクはリアルタイム処理に固執せず、時間帯を分散するかBatch APIに逃がす
- Bedrock/Vertex経由なら、そのプロバイダのコンソールでクォータを直接確認する
FAQ
429と529、結局何が違う?
429は自分(組織)側に設定された上限を超えたときのエラーで、対処の余地がある。529はAnthropic側の全体負荷で、自分の設定とは無関係に起きる。待つしかない529と、並列数やキャッシュで頻度を減らせる429は分けて考えたほうがいい。
429が出たらどれくらい待てば直る?
retry-afterヘッダーに秒数が入っているので、それが一番正確。ヘッダーが見えない場合(Claude Code本体を素で使ってる場合)は、体感だと数秒〜1分程度で解消することが多い。頻発するなら待つより並列数を見直すほうが根本対処になる。
Batch APIにもレート制限はある?
ある。ただしMessages APIとは別枠で、全モデル共通のRPMと処理キュー内のバッチリクエスト数上限という形になっている。大量処理をBatch APIに逃がしても無制限というわけではない点は注意。
レート制限自体を引き上げることはできる?
できる。Claude Consoleの「Rate limits」ページから「Request rate limit increase」を申請する形になる。急ぎならAnthropicサポートに直接連絡する経路もある。ただしBedrock/Vertex経由の場合はこのセルフサービス申請が使えないので、各クラウドの担当窓口経由になる。
429は「制限に引っかかった」という表示の強さの割に、実際は数秒〜数分で解消する一時的な現象であることが多い。使用量制限のように「今日はもう使えない」というものではないので、まず何が原因かを切り分けてから対処を考えれば、必要以上に焦らずに済むと思う。
Claude Codeもレート制限の仕組みも更新が速い領域なので、この記事の数値は執筆時点のものとして、最新の挙動は公式ドキュメントで確認してほしい。
