Claude 529 overloaded_error の対処法：連打する前の切り分けと安全な再試行

Claude の 529 overloaded_error は、Anthropic の公式API文書では Claude APIが一時的に過負荷になっている状態 を表します。429 rate_limit_error とは別のエラーです。

ただし、画面に「529」と出ただけでは、Claude Code、直接API、claude.ai、クラウド事業者、第三者ゲートウェイのどこが返したのかまでは確定できません。まず再試行を増やすのではなく、次の情報を保存してください。

• エラー本文を省略せず保存する
• 発生時刻とタイムゾーンを記録する
• 利用経路（Claude Code、Web、直接APIなど）、プロバイダー、モデル、クライアントのバージョンを記録する
• request_id または request-id ヘッダーを保存する
• すでに行われた自動・手動の再試行回数を数える
• 途中まで得られた出力と、実行済みのツール・書き込み処理を残す

この6点があれば、「少し待って再試行してよい失敗」なのか、「完了状態を確認するまで再送してはいけない失敗」なのかを判断しやすくなります。

まず結論：529を見た直後の判断順序

1. エラーと部分結果を保存する。 先に再実行すると、重要な相関情報や途中結果を失うことがあります。
2. 529を返した経路とプロバイダーを特定する。 Claude Codeと直接APIでは、すでに行われた再試行の扱いが違います。
3. 公式ステータスを確認する。 Anthropic直結なら Claude Status を、クラウドやゲートウェイ経由ならその事業者の状態も確認します。
4. 既存の再試行層を数える。 クライアント、SDK、アプリ、ジョブキューがそれぞれ再試行すると、意図せず大量のリクエストになります。
5. 処理が完了した可能性を確認する。 ストリーミング、ツール実行、購入、送信、書き込みを含む要求は、結果が不明なまま再送しません。
6. 安全と確認できた場合だけ、上限付きで再試行する。 retry-after が返っている場合はそれを尊重します。固定の待ち時間や回復時刻は保証されていません。

529・429・接続失敗は同じ扱いにしない

似た症状でも、次に見るべき場所が異なります。

VPNや回線の切り替えは、接続失敗の切り分けには役立つ場合があります。しかし、正式な 529 overloaded_error の原因をローカル回線だと決めつける根拠にはなりません。先にエラーの発生経路とレスポンスを確認する方が近道です。

どこで529を見たかによって対応を変える

Claude Codeで表示された場合

Claude Codeの公式エラー文書 によると、対象となる一時障害は指数バックオフで最大10回再試行され、その後にエラーが表示されます。つまり、画面に繰り返し529が出た時点で、すでに複数回の試行が行われている可能性があります。手動で何度もEnterを押したり、外側のスクリプトでClaude Code自体を再起動したりすると、再試行が重なります。

一方、完了済みのテキストブロックやツール呼び出しの後にストリームが失敗した場合、Claude Codeは同じツールを二重実行する危険を避けるため、その途中処理を自動でやり直しません。ここでは「もう一度送れば直る」より先に、ファイル変更、コマンド実行、外部送信などがすでに行われたかを確認します。

Claude Codeにおける繰り返し529は利用上限エラーではなく、Claude Codeのquotaには算入されないと公式文書に記載されています。ただし、この説明を直接APIや第三者ゲートウェイの課金へ広げることはできません。

公式SDKから直接APIを呼んでいる場合

AnthropicのAPIエラー文書 では、公式SDKは接続エラー、レート制限、5xx系の一時障害を指数バックオフで既定2回再試行し、retry-after がある場合は従うとされています。実際の挙動はSDKの言語、バージョン、max_retries 相当の設定によって変わります。

アプリ側にも再試行ループがあるなら、SDKの自動再試行を含めた総試行数を数えてください。たとえば外側が最大3回試し、そのたびに内側のSDKが初回を含めて最大3回送る構成なら、障害が続く間に上流へ最大9回届く設計になり得ます。設定名だけではなく、ログ上の実送信回数で確認するのが確実です。

claude.aiで表示された場合

画面のエラー文言、時刻、利用モデル、会話で最後に保存された内容を記録し、Claude Statusの claude.ai コンポーネントを確認します。ページ全体がOperationalでも、短時間、特定モデル、地域、アカウントに限られた失敗までは否定できません。ステータスが緑だからローカル障害、または赤だから個別リクエストも同じ原因、と一足飛びに結論づけないでください。

クラウド事業者・第三者ゲートウェイ経由の場合

表示された529がAnthropic由来なのか、中継側が独自に返したものなのかを先に確認します。

• 実際に送信したendpointとprovider名
• ゲートウェイのrequest IDと、保持されていれば上流request ID
• 上流ステータス、レスポンスヘッダー、エラー包装前の本文
• ゲートウェイ独自の再試行・フォールバック設定
• Anthropicと中継事業者それぞれのステータスページ

上流IDが置き換えられたり、公開されなかったりする実装もあり得ます。直接APIの再試行、quota、課金についての説明を、そのままゲートウェイに適用しないでください。

再試行の「所有者」を一つにする

安全な運用で重要なのは、指数バックオフの式そのものより、どの層が再試行を担当するか を決めることです。

自動化する場合は、少なくとも次の停止条件を持たせます。

• 最大試行回数
• 最大経過時間
• 同時実行数
• 1タスクあたりのコストまたはトークン予算
• 副作用を伴う要求の再送禁止条件
• 同じ原因が続くときのサーキットブレーカー
• 人へ切り替えるためのエスカレーション条件

CLAUDE_CODE_RETRY_WATCHDOG=1 は、無人のClaude Codeセッションで429・529の再試行を継続するための任意設定です。公式文書では容量エラーを無期限に、その他の一時障害の既定回数を300回へ増やす動作が説明されています。便利さと同時に、長時間の同時実行、予算、外部ツールの副作用を制御できる場合だけ検討すべき設定で、一般的な529対処として無条件に有効化するものではありません。

部分結果と副作用を確認してから再送する

AnthropicのAPIは、最初のHTTPレスポンスが 200 でも、SSEストリームの途中でエラーを返すことがあります。反対に、クライアントがタイムアウトした時点で、上流処理がどこまで進んだかはレスポンスだけでは分からない場合があります。

次のような要求は、完了状態が不明なまま再送しないでください。

• メール、メッセージ、フォームを送信する
• 購入、予約、決済、返金を行う
• データベースや外部APIへ書き込む
• ファイルを削除・移動・上書きする
• ツールでコマンドやデプロイを実行する

再送前に、対象システムの状態、操作ログ、利用記録を request_id と時刻で突き合わせます。対象APIが冪等キーや重複排除を保証しているなら、その仕様に従います。保証を確認できない場合、同じpayloadの再送で重複副作用や重複コストが発生しないとは言えません。

読み取り専用で副作用のない要求でも、部分回答を既存結果へ単純連結すると、重複や文脈の不整合が起きます。最後に確定した出力境界を保存し、「再開」できるのか「新規要求としてやり直す」のかを分けてください。

実務で使える復旧チェックリスト

1. 証拠を固定する

以下を一つの記録にまとめます。

text
発生時刻（タイムゾーン付き）:
利用経路: Claude Code / claude.ai / direct API / cloud / gateway
provider・endpoint:
モデル:
エラーtype・message:
request_id / request-id:
クライアント・SDK・バージョン:
自動再試行の設定と実送信回数:
手動再試行回数:
最後に受信した出力:
実行済みツール・外部副作用:
利用・課金記録で確認できたこと:
確認したstatus URLと時刻:

2. 状態を確認する

Anthropic直結ならClaude Statusで、該当する Claude API、Claude Code、claude.ai のコンポーネントを見ます。経由サービスがあるなら、その事業者の状態も同じ時刻帯で確認します。現在の表示だけでなく、エラー発生時刻に重なる履歴があるかを確認してください。

3. 再試行予算を決める

retry-after があれば従い、なければ利用中のSDKやサービスの文書を基準にします。固定秒数をAnthropicの保証として扱わず、試行回数と経過時間の両方に上限を置きます。復旧しない場合は、連打を続けるよりログをそろえて停止した方が診断しやすくなります。

4. 1回の検証を観測可能にする

安全に再送できる要求だけを選び、新しい試行の開始時刻とrequest IDを記録します。成功・失敗だけでなく、どの層が何回送信したかを確認します。これで次の再試行を推測ではなく記録に基づいて判断できます。

改善しない場合の問い合わせ情報

継続する529をサポートや運用担当へ渡すときは、次を添えると原因範囲を絞りやすくなります。

• 最初と最後の発生時刻、タイムゾーン
• 利用経路、provider、endpoint、モデル
• 完全なエラーtype・messageとHTTP/SSEのどちらか
• request_id または各経路の相関ID
• SDK・Claude Code・ゲートウェイのバージョン
• 各層の再試行設定と実送信回数
• 部分出力、ツール呼び出し、外部副作用の有無
• 該当時刻のステータス表示
• 利用記録・課金記録で確認できた範囲

request IDは照合の手掛かりですが、それだけで処理完了、課金、冪等性を証明するものではありません。完了状態や料金が争点なら、利用記録と副作用先のログも合わせて提示します。

よくある質問

529は自分の利用上限を超えたという意味ですか？

AnthropicのAPI文書では、529は一時的な過負荷、429はレート制限などとして区別されています。Claude Codeの繰り返し529も利用上限エラーではないと説明されています。ただし、第三者ゲートウェイが独自にエラーを包装している場合は、その事業者の仕様を確認してください。

Claude StatusがOperationalなら、自分の環境が原因ですか？

断定できません。公開ステータスは集約情報であり、短時間、特定モデル、経路、地域、アカウントに限られた失敗を必ず表すとは限りません。エラー本文、時刻、provider、request IDと合わせて判断します。

何分待てば直りますか？

すべての529に共通する固定の復旧時間は確認されていません。retry-after、利用中のSDK・サービスの文書、現在のステータス、社内の再試行予算に従ってください。

モデルを切り替えれば解決しますか？

Claude Codeの公式文書では、容量がモデルごとに追跡されるため、モデル切り替えが回復手段として示されています。ただし、利用経路でそのモデルが選べること、品質や機能がタスクに合うこと、契約・データ取扱いの条件を満たすことが前提です。万能な回避策ではありません。

529の要求は課金されませんか？

Claude Codeについては、繰り返し529はClaude Code quotaに算入されないと公式文書にあります。しかし、直接API、ストリーム途中失敗、第三者ゲートウェイの課金や重複コストを一律に判断できる公開ルールは確認できません。request ID、利用記録、ゲートウェイ記録で個別に照合してください。

最後に：速い復旧は、再試行回数ではなく観測から始まる

529 overloaded_error は一時的な過負荷を示しますが、それだけで現在の全体障害、個別リクエストの完了状態、課金結果までは分かりません。

最初に発生経路とproviderを特定し、request ID、時刻、部分結果、既存の再試行を保存してください。そのうえで状態を確認し、再送が安全な要求に限って上限付きで試します。この順序なら、retry stormや二重実行を避けながら、復旧とエスカレーションのどちらにも進めます。