Claude Code を使っていると、API Error: 500、Repeated 529 Overloaded errors、Request timed out、You've hit your session limit といったメッセージに出会うことがあります。多くは一時的なもので Claude Code が自動で再試行していますが、自分の設定や認証情報が原因のものは手で直す必要があります。この記事では、公式ドキュメント「Error reference」をもとに、自動リトライのしくみ、リトライとタイムアウトを調整する環境変数、サーバーエラー・途中切断・認証・使用量上限の各エラーの意味と対処を整理します。インストールやログインの段階で出るエラーはインストールとログインのトラブル対処の記事を参照してください。
自動リトライのしくみ
公式ドキュメントによると、ここで扱う実行時のエラーは CLI・デスクトップアプリ・クラウドのセッションで共通です。また、ほとんどのエラーはその下にある API のエラーコードに対応しており、HTTP ステータスそのものの定義は Claude Platform 側のエラーリファレンスにまとまっています(API を直接呼ぶ場合はClaude API のエラーの記事も参照)。
Claude Code は一時的な失敗を最大10回、指数バックオフで自動的に再試行します。再試行の対象と対象外は次のとおりです。
| 自動で再試行するもの | 再試行しないもの |
|---|---|
| 応答がまだ流れ始める前に起きたサーバーエラー・過負荷・タイムアウト/応答が出る前に接続が切れた・止まった場合 | TLS 証明書の失敗/Claude がテキストやツール呼び出しを出し終えた後の途中失敗/応答が完了した後の失敗 |
再試行中はスピナーに Retrying in Ns · attempt x/y のように待ち時間と試行回数が表示されます。また、データが届かない状態が20秒以上続くと「API の応答待ち」であることを示す表示が出ます(ゲートウェイ経由の場合、v2.1.309 以降は45秒)。画面にエラーが出るのは、こうした再試行を使い切った後か、そもそも再試行の対象外だった場合です。
リトライを調整する環境変数
再試行の回数や待ち時間は環境変数で調整できます。公式のエラーリファレンスに載っている主なものは次のとおりです(バージョン条件のあるものは、claude --version で手元のバージョンを確かめてから使います)。
| 変数 | 既定値 | 働き |
|---|---|---|
CLAUDE_CODE_MAX_RETRIES | 10 | 再試行の回数。v2.1.186 以降は上限15 |
CLAUDE_CODE_RETRY_WATCHDOG | 未設定 | 1 にすると、無人のセッションで 429 と 529 を無期限に再試行する |
CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS | 未設定 | ウォッチドッグ有効時の 429/529 の待ち時間の上限(v2.1.295 以降) |
CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS | 500 | 529 再試行の最初の待ち時間(v2.1.292 以降) |
CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS | 32000 | 529 再試行の待ち時間の上限(v2.1.296 以降) |
API_TIMEOUT_MS | 600000 | 各試行が応答ヘッダーを受け取るまでの時間(ミリ秒) |
CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS | 未設定 | ストリーミング要求の最初のバイトまでの期限(v2.1.242 以降) |
環境変数リファレンスでは、API_TIMEOUT_MS は「応答ヘッダーを受け取るまで」の制限で、ストリーミングが始まった後の長さは制限しないと説明されています。遅い回線やプロキシ経由でタイムアウトする場合に値を増やし、0 にすると制限を外せます(v2.1.305 以降。その場合でも非ストリーミングの試行はローカルでは300秒で打ち切られます)。また CLAUDE_CODE_MAX_RETRIES については、529 では設定回数より早く止まることがあり、フォールバックモデルを設定していればエラーを出す代わりにそのモデルへ切り替わる、と補足されています。長い障害を待ち続けたい無人の実行では、回数を増やすより CLAUDE_CODE_RETRY_WATCHDOG を使うよう案内されています。
# 例: プロキシ経由で応答ヘッダーが遅い環境で待ち時間を20分にする
export API_TIMEOUT_MS=1200000
claude
サーバーエラーとタイムアウト
再試行を使い切っても解決しなかったときに出る代表的なメッセージです。
API Error: 500 Internal server error: API 側の予期しない内部障害で、プロンプトや設定、アカウントが原因ではありません。status.claude.com(またはクラウドプロバイダーのステータスページ)を確認し、少し待って送り直します。長いプロンプトならtry againと入力するだけで構いません。ANTHROPIC_BASE_URLでゲートウェイを指していてすべての要求が失敗する場合は、ゲートウェイがツール検索のフィールドを受け付けるかを確認します。障害情報が出ていないのに続く場合は/feedbackで報告します。API Error: Repeated 529 Overloaded errors: API の処理能力が一時的に足りない状態です。529 は利用枠(クォータ)には数えられません。数分後に再試行するか、処理能力はモデルごとに管理されているため/modelで別のモデルに切り替えます。Request timed out: 既定の要求タイムアウトは10分です。遅い回線やプロキシが原因ならAPI_TIMEOUT_MSを増やします。API_TIMEOUT_MS=0にしたのにすべて失敗する場合は、v2.1.305 より前のバージョンでないかをclaude --versionで確かめ、更新するか正の値を設定します。API Error: No response from API: ストリーミング要求を送ったものの、最初のバイトの期限までに応答ヘッダーが返らなかった状態です。まず送り直し、繰り返すならネットワークやプロキシの問題として扱います。応答が完了するまでまとめて保持するプロキシやゲートウェイがある環境では、API_TIMEOUT_MSまたはCLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MSを増やして待ち時間を延ばします。
社内プロキシや独自の CA を使う環境で接続そのものができない場合は、プロキシ・社内CA・mTLS の設定も確認してください。
応答が途中で切れたとき
Claude が応答を書いている最中に失敗すると、それまでの出力は残ったまま、次のようなメッセージが表示されます。いずれも末尾に「The response above may be incomplete.(上の応答は不完全な可能性がある)」と付きます。
| メッセージ | 起きたこと |
|---|---|
API Error: Server error mid-response. | 応答の途中で過負荷や 5xx のエラーが起きた |
API Error: Connection lost mid-response. | 接続が切れた |
API Error: Your computer went to sleep mid-response. | 受信中にマシンがスリープした |
API Error: The response stopped arriving. | 止まったストリームをアイドル監視が打ち切った |
前述のとおり、Claude がテキストやツール呼び出しを出し終えた後の失敗は自動では再試行されません。対処はどれも同じで、途中までの出力を読んでから、対話セッションで continue と返信します。-p(ヘッドレスモード)で実行していた場合は、セッションを再開して continue を送ります。Amazon Bedrock で、最初の試行がタイムアウトして再試行では成功するという状態が続く場合は、CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS を増やすよう案内されています。
認証と使用量上限のエラー
認証のエラーは、今どの認証情報が使われているかを /status で確かめるのが出発点です。意図しない ANTHROPIC_API_KEY が残っていてログインより優先されている、というのがよくある原因です。
| 表示 | 対処 |
|---|---|
Not logged in · Please run /login | /login を実行する。環境変数で認証するつもりなら、起動したシェルで ANTHROPIC_API_KEY が export されているか確認する。CI では apiKeyHelper スクリプトを設定する |
Invalid API key · Fix external API key | キーの打ち間違いや失効を Console で確認する。env | grep ANTHROPIC(PowerShell は Get-ChildItem Env:ANTHROPIC*)で設定を見て、unset ANTHROPIC_API_KEY の後に /login |
Your apiKeyHelper script is failing | ヘルパーを直接実行して確かめる。標準出力にはキーだけを出し、終了コード0で終わるようにする。ヘルパーが設定されている間は /login では直らない |
OAuth token revoked / Login expired | /login を実行する。CLAUDE_CODE_OAUTH_TOKEN を設定している場合は claude setup-token で新しいトークンを作るか、変数を外して /login |
API Error: 401 Invalid authentication credentials | /status で確認し、API キーが有効ならローテーションするか外す。ログインだけなら /login。同じログインで失敗し続けるなら管理者にアクセスの復旧を依頼する |
使用量の上限に達した場合は、次のようなメッセージになります。
You've hit your session limit · resets 3:45pm(weekly limit・Opus limit・Sonnet limit も同様): 表示された時刻まで要求が止まります。/usageで状況を確認し、Opus や Sonnet の上限なら/modelで別系統のモデルに切り替えれば作業を続けられます。追加の利用枠は/usage-creditsかプランのアップグレードで得られます。Usage credits required for 1M context: 1M トークンのコンテキストには使用量クレジットが必要です。/modelで[1m]の付かない版を選ぶか、/usage-creditsで有効にしてから再起動します。1M の選択肢自体を隠すにはCLAUDE_CODE_DISABLE_1M_CONTEXT=1を設定します(1M トークンのコンテキストも参照)。Server is temporarily limiting requests (not your usage limit): サーバー側の短時間の抑制で、自分の上限ではありません。待って再試行します。API Error: Request rejected (429): API キーや Bedrock・Google Cloud のプロジェクトがレート制限に達しています。/statusで認証情報を確かめ、プロバイダーのコンソールで上限を確認し、並列のサブエージェントを減らすなどして同時実行を抑えます。Credit balance is too low: Console の組織のクレジット切れか、意図しない API キーが使われています。/statusで確認し、不要なANTHROPIC_API_KEYを外すか、Console の請求設定でクレジットを追加します。
利用状況やコストの把握についてはコストを効果的に管理するの記事が参考になります。
本記事は Claude Code 公式ドキュメント「Error reference」を元に、同じく公式の Environment variables で API_TIMEOUT_MS・CLAUDE_CODE_MAX_RETRIES・CLAUDE_CODE_DISABLE_1M_CONTEXT の説明を照合した非公式の日本語解説です(確認日 2026-11-18)。エラー文や既定値、必要なバージョンは更新される可能性があるため、利用前に公式ドキュメントをご確認ください。