Claude Code のエラー・利用制限まとめ：429/529/rate limit の見分け方と対処

Claude Code を使っていると、429 や 529、「limit」を含むメッセージに出会うことがあります。どれも「止まった」ように見えますが、原因も対処もまったく違います。待てば直るもの、モデルを変えれば続けられるもの、設定の間違いが原因のものがあります。

この記事では、エラーの表示を実際に再現して確認したものと公式ドキュメントからの引用に分けて整理し、見分け方と対処をまとめます。

検証環境

項目	内容
確認日	2026-10-19
Claude Code	2.1.303（ネイティブ版、Claude Pro でログイン）
OS	Debian GNU/Linux 13（trixie）
モックサーバー	Python 3.13.5 の標準ライブラリ（http.server）で作成
モデル	--model haiku

先に結論：メッセージ別の見分け方

メッセージ（抜粋）	何が起きたか	主な対処	出典
You've hit your session limit · resets 3:45pm	プランのセッション枠を使い切った	リセット時刻まで待つ、/usage で確認	公式ドキュメント
You've hit your weekly limit · resets ...	プランの週の枠を使い切った	同上（モデルを変えても戻らない）	公式ドキュメント
You've hit your Opus limit / Sonnet limit	そのモデルの枠を使い切った	/model で別のモデルに切り替え	公式ドキュメント
API Error: Server is temporarily limiting requests (not your usage limit)	プランとは無関係の一時的な制限	少し待つ	公式ドキュメント
API Error: Request rejected (429) · ...	API キーなどのレート制限	/status で認証情報を確認、同時実行を減らす	公式ドキュメント／モックで再現
API Error: 529 Overloaded. ...	API 全体が混雑（使用量とは無関係）	数分待つ、/model で別モデル	モックで再現
API Error: Repeated 529 Overloaded errors. ...	同上	同上	公式ドキュメント
API Error: 500 Internal server error. ...	サーバー側の障害	少し待って再送、status.claude.com を確認	公式ドキュメント／モックで再現
Invalid API key · Fix external API key	環境変数などの API キーが無効	unset ANTHROPIC_API_KEY	実機で再現（本物の API）

/status と /usage で状態を確認する

困ったら、まずこの 2 つを開きます。下の画面は /status を開いたあとに Usage タブへ切り替えたものですが、そのセッションの Total cost は $0.0000、トークンも 0 input, 0 output のままでした。開くだけでモデルが呼ばれることはなさそうです。

/usage：プランの残りとリセット時刻

• Current session と Current week の 2 本のバーが出ました。リセット時刻はタイムゾーン付き（この環境では Asia/Tokyo）です。
• 下の「What’s contributing to your limits usage?」には、このマシンのローカルセッションに基づく概算として、並列で動かしたセッションに関する統計や、スキル・MCP サーバーごとの割合が出ていました（画像では数値を伏せています）。「全セッションで 1 つの枠を共有している」という注意も表示されています。

/status：今どの認証情報が使われているか

Login method にプランが出ていれば、サブスクリプションで動いています。次の章のように API キーが使われていると、表示が変わります。

ANTHROPIC_API_KEY が優先される問題を確かめる

公式ドキュメントには、環境変数 ANTHROPIC_API_KEY が設定されていて承認されると、サブスクリプションより優先されると書かれています。古いキーが .bashrc や .env に残っていると、「Pro なのに 429 が出る」「Invalid API key と言われる」原因になります。

わざと無効なダミーのキー（sk-ant-dummy-invalid）を設定して確かめました。

claude -p ではそのままキーが使われる

• claude -p は、確認なしでダミーのキーを使い、Invalid API key · Fix external API key で失敗しました（終了コード 1）。この一回は本物の API に無効なキーで接続した結果で、モデルは動いていません。
• あわせて「ANTHROPIC_API_KEY などが設定されているので claude.ai のコネクタは無効」という警告も出ました。
• claude auth status には apiKeySource: "ANTHROPIC_API_KEY" が追加されました。なお、出力をパイプに通したとき（| grep など）は authMethod が api_key と表示され、端末に直接出したときは claude.ai のままでした。表示の違いの理由は未確認です。

対話モードでは最初に確認される

対話モードで起動すると、キーを使うかどうか聞かれました。**初期選択は「No (recommended)」**です。

ここで Yes を選ぶか、あとから /config の Use custom API key をオンにすると、キーが使われるようになります。

オンにした後の /status では、ログインが 「not in use」（使われていない） と表示されました。

画面上部のヘッダーは「Claude Pro」のままだったので、どちらが使われているかはヘッダーではなく /status で確認するのが確実です。

元に戻す

unset ANTHROPIC_API_KEY

対話モードで承認した記録は ~/.claude.json の customApiKeyResponses に残っていました（承認したキーの文字列がそのまま入っていました）。検証後は承認を取り消してあります。

429・529・500 をモックサーバーで再現する

ここからはモックサーバーを使います。ANTHROPIC_BASE_URL で接続先を手元のサーバーに向け、ANTHROPIC_API_KEY にはダミーの値を入れました（こうすると本物のアカウント情報が送られず、使用量も増えません）。

モックサーバーは、/v1/messages へのリクエストに決まったステータスと Anthropic 形式のエラー JSON を返し、届いた時刻・メソッド・パスだけを記録します（ヘッダーは記録しません）。

"""検証用のモック API サーバー。/v1/messages に指定ステータスを返し続ける。
リクエストヘッダーは記録しない（認証情報を残さないため）。"""
import json, sys, time
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

STATUS = int(sys.argv[1])          # 返す HTTP ステータス（429 / 529 / 500 など）
PORT = int(sys.argv[2]) if len(sys.argv) > 2 else 8529
BODIES = {
    429: {"type": "error", "error": {"type": "rate_limit_error", "message": "mock: rate limited"}},
    529: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}},
    500: {"type": "error", "error": {"type": "api_error", "message": "Internal server error"}},
}
T0 = time.time()

class H(BaseHTTPRequestHandler):
    def _reply(self):
        n = int(self.headers.get("content-length") or 0)
        if n:
            self.rfile.read(n)
        body = json.dumps(BODIES.get(STATUS, BODIES[500])).encode()
        self.send_response(STATUS)
        self.send_header("content-type", "application/json")
        self.send_header("content-length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)
        print(f"+{time.time()-T0:7.2f}s {self.command} {self.path.split('?')[0]} -> {STATUS}", flush=True)
    do_POST = do_GET = do_HEAD = _reply
    def log_message(self, *a):
        pass

print(f"mock API: always {STATUS} on 127.0.0.1:{PORT}", flush=True)
ThreadingHTTPServer(("127.0.0.1", PORT), H).serve_forever()

再試行の回数を 2 回に減らして（CLAUDE_CODE_MAX_RETRIES=2）、それぞれ実行しました。

529 Overloaded

表示は API Error: 529 Overloaded. This is a server-side issue, usually temporary — try again in a moment. If it persists, check your inference gateway (127.0.0.1:18529). でした。

429

API Error: Request rejected (429) · mock: rate limited と表示されました。「·」の後ろはサーバーが返したメッセージで、モックの文言がそのまま出ています。公式ドキュメントの例では this may be a temporary capacity issue. ... となっているので、本物の API では違う文が入るはずです（未確認）。429 も 529 と同じく、3 回の POST が届いた（再試行された）ことがログからわかります。

500

API Error: 500 Internal server error. This is a server-side issue, usually temporary — try again in a moment. If it persists, check your inference gateway (127.0.0.1:18500). と表示されました。

再試行の回数と間隔

公式ドキュメントでは、一時的な障害は指数バックオフで最大 10 回まで再試行し、その後にエラーを表示するとされています。モックのログで実際の回数と間隔を数えました。

既定（CLAUDE_CODE_MAX_RETRIES 未設定）の場合

529 を返し続けるモックに、既定の設定で 1 回だけ claude -p を送ったときのログです（数値はモックが記録した、サーバー起動からの経過秒）。

POST	経過（秒）	前回からの間隔（秒）
1 回目	1.44	—
2 回目	2.07	0.63
3 回目	3.20	1.13
4 回目	5.47	2.27
5 回目	9.86	4.39
6 回目	19.14	9.28
7 回目	35.96	16.82
8 回目	73.80	37.84
9 回目	109.62	35.82
10 回目	145.40	35.78
11 回目	181.89	36.49

• POST は 11 回（最初の 1 回＋再試行 10 回）で、ドキュメントの「最大 10 回」と一致しました。
• 間隔はほぼ倍々に伸び、後半は 36 秒前後で頭打ちになりました。エラーが表示されるまで、最初の POST から約 3 分かかっています。
• 529 の待ち時間の初期値は 500 ミリ秒、上限は 32000 ミリ秒とドキュメントにあります。実測の間隔が上限より数秒長いのは、ランダムな揺らぎや通信時間が含まれるためと思われますが、内訳は未確認です。
• どの場合も、POST の前に HEAD /api/hello が 1 回届いていました（接続確認と思われます）。

対話モードでの表示

対話モードで同じことをすると、スピナーの位置に再試行のカウントダウンが出ます。待ち時間がわかりやすいよう、CLAUDE_CODE_MAX_RETRIES=4 と CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS=4000 を設定しました。

• 最初は API error · Retrying in 2s · attempt 1/4、3 回目から 529 Overloaded · Retrying in 17s · attempt 3/4 と理由が具体的になりました。ドキュメントの「その他のエラーでは最初は API error と表示され、v2.1.198 以降では 3 回目の試行から具体的な理由に切り替わる」という記述と一致します。
• 起動時には Both claude.ai and ANTHROPIC_API_KEY set · auth may not work as expected という警告と、ヘッダーに「API Usage Billing」という表示が出ていました。

再試行を調整する環境変数

公式ドキュメントのエラーリファレンス（「再試行の動作を調整する」）に載っている主な変数です。

変数	既定	内容	この記事で
CLAUDE_CODE_MAX_RETRIES	10	再試行の回数。v2.1.186 以降は上限 15	2 と 4 で確認
CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS	500	529 の再試行の待ち時間の初期値（最大 32000）	4000 で使用
CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS	32000	529 の再試行の待ち時間の上限（最大 64000）	未確認
CLAUDE_CODE_RETRY_WATCHDOG	未設定	1 で 429/529 の容量エラーを無期限に再試行（CI など無人実行向け）	未確認
CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS	未設定	上記の待ち時間の上限（v2.1.295 以降）	未確認
API_TIMEOUT_MS	600000	リクエストごとのタイムアウト	未確認

スクリプトや CI で早く失敗させたいなら CLAUDE_CODE_MAX_RETRIES を小さく、混雑時に粘りたいなら待ち時間を長くする、という使い分けになります。

使用量を減らすためにできること

利用制限に当たりにくくするための方法です。公式ドキュメント（コスト管理のページ）の内容に、今回見た画面を添えています。

• 関係ない作業に移るときは /clear。古い会話はその後のすべてのメッセージで読み込まれます。
• 長くなったら /compact。/compact コードの変更点を中心に のように、残してほしい内容を指定できます。
• 軽い作業は軽いモデルで。/model で切り替えます（この記事の検証もすべて haiku で行いました）。
• 使っていない MCP サーバーを無効にする。/mcp から無効化できます（MCP の設定記事）。
• 長い手順書は CLAUDE.md ではなくスキルに移す。スキルの本文は使われるときだけ読み込まれます（Skills の記事）。
• 並列で動かすセッションを減らす。/usage の画面にも「全セッションで 1 つの枠を共有している」と表示されていました。

何がコンテキストを使っているかは /context で見られます。

この環境では、何も話していない状態で 28.3k/1m tokens でした。claude.ai から同期されたスキルが 41 個あり、その説明だけで 7.1k トークンになっています。

/compact や /clear で実際にどれだけ減るか、モデルによって推定コストがどれだけ違うかは、トークン節約の記事で測っています。

まとめ

hooks を使えば、エラーで止まったときにスマホへ通知することもできます（hooks の記事）。

参考

• エラーリファレンス（公式）
• 認証（公式）
• コストを効果的に管理する（公式）
• 環境変数リファレンス（公式）

この記事は、AI を使って下書きを作り、手順とコマンドの出力・画面は筆者の検証環境で実際に実行して確認しています。429・529・500 の表示は、手元のモックサーバーで再現したものです。アイキャッチ画像は生成画像（イラスト）で、実際の画面ではありません。