Claude APIエラーを解説：サーバーエラー500、過負荷529、レート制限429、不正なリクエスト400 — それぞれの解決方法

Claude APIを使う開発者は、いずれエラーに遭遇します。原因が利用者側にあるもの（不正な形式のリクエスト）、Anthropic側にあるもの（サーバーの問題）、アーキテクチャに起因するもの（高負荷利用時のレート制限）があります。このガイドでは、一般的なClaude APIの各エラーコードについて、実際の原因、具体的な解決方法、本番環境で使える再試行ロジックを紹介します。また、複数の上流アカウントを持つゲートウェイ経由でルーティングすることで、レート制限や過負荷エラーの発生頻度をどのように減らせるかも説明します。

再試行する前にアクセス権とモデルを確認する

プランまたは残高によるアクセスが有効であることを確認し、キーグループを調べ、そのキーに対して返されたモデルを使用してください。モデル一覧のレスポンスが正常に返ることは、初期確認にすぎません。大規模なエージェント実行の前に、小さな生成リクエストが成功することを確認しましょう。

使用するモデルは、 モデルとキーグループ と エージェント設定チェックリスト を参照して、アクセスの問題をツール設定や上流サービスのエラーと切り分けてください。

「Claudeのサーバーエラー」：実際にはどのエラーですか？

「Claudeのサーバーエラー」は、APIが応答しなくなったときに人々が検索する言葉ですが、対処方法を決めるのはメッセージ内の番号です。**500**はAPI内部の障害を意味します。待機する、再試行する、またはモデルを切り替えてください。**529**はモデルがすべての利用者に対して飽和状態になっていることを意味します。対処方法は同じで、時間がたてば解消します。**429**は利用制限に達したことを意味します。処理速度を落とすか、並列リクエストを減らしてください。

**400**はリクエスト自体が拒否されたことを意味します。同じ内容で再試行しても再び失敗します。以下で該当するコードを探してください。各セクションには、正確なメッセージ、原因、解決方法が記載されています。自分のコードではなくClaude Code内でエラーが発生している場合は、/claude-code/errors/にあるClaude Codeのエラーガイドで、CLI固有のメッセージ（OAuthのタイムアウト、「プロセスがコード 1 で終了しました」、ツール使用の同時実行）を確認できます。

エラー 400 — 不正なリクエスト

400エラーは、リクエストの構造が無効であることを意味します。Claude APIは、応答の生成を試みる前にリクエストを拒否しました。エラー本文には問題を説明するメッセージが含まれているため、必ず注意深く読んでください。よくある原因には、messages配列が空または不正な形式である、contentフィールドが文字列ではなくnullになっている、max_tokensがモデルの上限を超えている、モデル識別子が存在しない、システムプロンプトの形式が正しくない、ツール定義のスキーマにエラーがある、といったものがあります。

Claude Codeの利用者に最もよく発生する400エラーは、コンテキスト長の超過です。会話履歴がモデルのコンテキストウィンドウ（多くのClaudeモデルでは200Kトークン）を超えると、APIは入力が長すぎる旨のメッセージとともに400を返します。解決するには、/compactで履歴を要約する、コンテキストから大きなファイルの内容を削除する、または新しいセッションを開始してください。これはレート制限ではなく、リクエストサイズに対する厳格な制約です。

よくある別の400の原因は、サポートされていないパラメーターやモデルバージョンの送信です。最近SDKをアップグレードしたり、モデル識別子を変更したりした場合は、リクエストのすべてのフィールドが現在のAPI仕様に一致しているかを再確認してください。モデルIDは大文字と小文字を区別し、バージョンごとに異なります。'claude-opus-4-6'は有効ですが、'Claude-Opus-4.6'は無効です。判断に迷う場合は、/v1/modelsエンドポイントに問い合わせ、プロバイダーが受け付ける識別子を正確に確認してください。

エラー 400 — 「指定されたモデルには入力が長すぎます」

この特定の400エラーは、リクエスト（システムプロンプト＋メッセージ＋ツール定義）がモデルのコンテキストウィンドウを超えていることを意味します。これはレート制限ではなく、再試行しても解決しません。入力を減らすか、より大きなコンテキストを扱えるモデルに移行するまで、同じペイロードは毎回失敗します。

実用的な対処方法を、必要な手間が少ない順に紹介します。まず、再送信する会話履歴を削減してください。多くのチャットアプリに必要なのは、全文の記録ではなく、直近の数回のやり取りと随時更新する要約だけです。次に、送信前にトークン数を数え（トークン計数エンドポイントは無料です）、コード内で入力予算の厳格な上限を設けてください。最後に、リポジトリ全体や書籍ほどの長さの文書など、完全なコンテキストが本当に必要な場合は、Fable 5のような1Mのコンテキストに対応するモデルに切り替えてください。同じリクエストでも余裕を持って収まります。

エージェント型ツールでよくある落とし穴として、長時間のセッションではツールの結果やファイルの内容が蓄積し、さらにやり取りを続けた時点でリクエストが上限を超えることがあります。Claude Codeや同様のエージェントでセッションの途中にこのエラーが発生した場合は、プロンプトを短くするのではなく、セッションのコンテキストを圧縮するかクリアしてください。

エラー 429 — 「レート制限に達しました」/「レートを超過しました」

同じ状態が異なる表現で表示されます。APIはHTTP 429を、次の内容とともに返します rate_limit_error。claude.aiとClaude Codeでは、これが「レートを超過しました」または「レート制限に達しました」と表示されます。どちらの文言が表示されても、原因は同じです。現在の期間におけるアカウントの利用枠を使い切っており、リセットされるまでリクエストが拒否されます。

429は、許可されたリクエストレートを超えたことを意味します。レスポンスにはRetry-Afterヘッダーが含まれ、再試行まで何秒待つべきかが示されます。Anthropicのレート制限には、毎分のリクエスト数（RPM）、毎分のトークン数（TPM）、日ごとのトークン数（TPD）という複数の指標があります。いずれかの上限に達すると429が発生します。通常、エラーメッセージにはどの上限に達したかが示されます。

Claude Codeの利用者にとって、レート制限はワークフローを中断するため、最もストレスの大きいエラーです。開発者が単独でClaude Codeとサブエージェントを実行していても、並列処理中にRPMの上限に達したり、大きなファイルをコンテキストに含むセッション中にTPMの上限に達したりすることは容易に起こります。上限はアカウントのティアによって異なります。下位ティアでは制限が厳しく、エージェントを多用すると日常的に上限を超えます。

429への適切な対応は、ジッターを加えた指数バックオフです。Retry-Afterで指定された時間だけ待機してから、ランダムな遅延を追加します。これにより、複数のクライアントが同時に上限に達した場合のリクエスト集中を防げます。AI Prime Tech Unlimitedのようなゲートウェイは、複数の上流アカウントにリクエストを振り分けることで、利用可能なレート制限枠を実質的に増やし、429エラーの削減に役立ちます。ある上流アカウントがレート制限を受けると、ゲートウェイは別のアカウントに振り分けます。

エラー500 — 内部サーバーエラー

500エラーは、サーバー側で何らかの問題が発生したことを意味します。ユーザーに原因があるわけではなく、リクエストを変更しても解決できません。これは一時的なエラーであり、500で失敗したリクエストも、少し待ってから再試行すれば成功する可能性が高いです。Anthropicのインフラは、デプロイ、処理容量の変更、内部サービスの障害などの際に、500エラーを返すことがあります。

500エラーへの適切な対処は、バックオフを伴う単純な再試行です。1-2秒待ってから、まったく同じリクエストを再試行します。再び失敗した場合は4秒、次に8秒と待機時間を延ばし、最大で約60秒まで増やします。ほとんどの500エラーは、最初の再試行で解消します。500エラーが数分以上続く場合は、Anthropicのステータスページまたはゲートウェイのステータスエンドポイントで、既知の障害を確認してください。

500が発生しても、リクエストを変更しないでください。問題はサーバー側にあります。プロンプトの変更、コンテキストの削減、モデルの切り替えは役に立たず、自分に原因のない問題のデバッグに開発時間を費やすことになります。必要な対応は、再試行すること、再試行が失敗したら待機時間を延ばすこと、妥当な時間を超えて問題が続く場合（5-10分間連続して失敗する場合）にアラートを出すことだけです。

エラー529 — 「Claudeサーバーが過負荷状態です」（overloaded_error）

529ステータスコードはAnthropic固有のもので、APIへの需要が高まっていること、つまりリクエストしたモデルが一時的に処理容量の上限に達していることを意味します。429（YOURのレート制限を超過したことを意味します）とは異なり、529は、個別の利用上限に関係なくSYSTEMが過負荷状態にあることを意味します。ユーザーが何か間違ったわけではありません。その時点で、利用可能な計算リソースを需要が上回っているだけです。

529エラーは、ピーク時間帯（米国の営業時間）、新しいモデルのリリース直後（全員が同時に新モデルを試すとき）、話題が急速に広まり全顧客の利用量が急増するときに特に多く発生します。SonnetやHaikuではOpusよりも発生頻度が低くなります。Opusはリクエストあたりに必要な計算リソースが多く、処理容量の制約も厳しいためです。

529エラーには、500エラーよりも長いバックオフで対処してください。まず5-10秒待ち、待機時間を指数関数的に増やします。本番システムを構築する場合は、モデルのフォールバックを検討してください。Opusが529を返したら、そのリクエストをSonnetにフォールバックします。複数の上流アカウントを持つゲートウェイも役立ちます。過負荷の影響はアカウントの優先度階層によって異なる場合があり、需要のピーク時でもゲートウェイが選べる振り分け先が増えるためです。

「正常な上流接続先がありません」— Claudeのエラーではなく、インフラのエラー

「No healthy upstream」は、Claude API自体が返すメッセージではありません。ロードバランサーやイングレスプロキシ（通常はEnvoy）が、その背後にあるすべてのバックエンドインスタンスを利用できない場合に出力するメッセージです。障害時にはclaude.aiで表示されるほか、上流接続のプールが枯渇している、またはヘルスチェックに失敗しているプロキシやゲートウェイからも返されます。

コードで修正すべきことはありません。一時的な問題として扱い、status.anthropic.comを確認し、待機してから、529の場合と同じように指数バックオフで再試行してください。公式エンドポイントで数分以上続く場合はサービス障害です。サードパーティのゲートウェイから返される場合は、そのゲートウェイが上流の処理容量をすべて失っています。

これは、複数アカウントを持つゲートウェイが吸収するように設計されている障害のひとつです。ある上流アカウントがスロットリングを受けたり、正常に動作していなかったりする場合、エラーをユーザーに返す代わりに、リクエストを別のアカウントへ振り分けます。

本番運用に対応した再試行ロジック

適切な再試行ロジックは、すべての一時的なエラー（429、500、529）を、指数バックオフとジッターで一律に処理し、恒久的なエラー（400、401、403）は再試行不可として扱います。処理の流れは、リクエストを実行し、ステータスコードを確認し、再試行可能ならバックオフで待機して最大N回まで再試行し、再試行不可なら直ちに例外を送出する、というものです。ほとんどのアプリケーションでは、最大再試行回数を3-5に設定するのが適切です。

ジッターは、再試行のタイミングが揃うのを防ぎます。複数のクライアントが同時にレート制限に達し、すべてがちょうど2秒後に再試行すると、再び同時に失敗してしまいます。ランダムなジッターを加える（遅延時間に0.5から1.5の範囲のランダムな係数を掛ける）ことで、再試行のタイミングを分散させ、成功率を大幅に高められます。本番環境で使用するすべてのClaude APIクライアントには、ジッターを組み込むべきです。

Claude Codeやエージェント型ワークフローでは、HTTPクライアントのレベルで再試行を実装すると、個々のツール呼び出しやサブエージェントのリクエストにも自動的に適用されます。Anthropic SDKには基本的な再試行ロジックがすでに含まれていますが、ユースケースに応じてタイムアウトや最大再試行回数を調整するとよいでしょう。AI Prime Tech Unlimitedを使用する場合、ゲートウェイが上流への再試行とルーティングを内部で処理するため、そもそもクライアントに返されるエラーが減ります。

ゲートウェイがこれらのエラーを減らす仕組み

AI Prime Tech Unlimitedのような適切に設計されたゲートウェイは、さまざまな方法でエラーの発生頻度を減らします。レート制限（429）については、複数の上流APIアカウントにリクエストを分散するため、実効的なレート制限は、単一アカウントの割り当てではなく、すべての上流アカウントの合計になります。過負荷エラー（529）については、優先度やキュー内の位置が異なる可能性のある別の上流アカウントで再試行できます。

サーバーエラー（500）については、ゲートウェイがクライアントにエラーを返す前に透過的に再試行できます。そのため、エラーの代わりに、応答が少し遅くなるだけで済みます。400エラーについては、リクエスト自体が無効なためゲートウェイでは解決できませんが、優れたゲートウェイは、Anthropicの生のエラーレスポンスよりもわかりやすいエラーメッセージを提供し、デバッグを迅速に進められるようにします。

結果として、開発者にとっては、アプリケーションに届くエラーが減り、クライアント側で必要な再試行ロジックが少なくなり、ピーク時間帯のパフォーマンスがより安定します。これは、タスクの途中でエラーが発生すると作業の流れが途切れるClaude Codeのセッションや、エラー率がユーザー体験に直接影響する本番アプリケーションで特に有益です。無制限プランは定額制のため、これらの再試行や再ルーティングに追加料金はかかりません。

import anthropic
import time
import random

client = anthropic.Anthropic(
    api_key="YOUR_KEY",
    base_url="https://aiprimetech.io",
)

def call_with_retry(messages, model="claude-sonnet-4-5", max_retries=4):
    for attempt in range(max_retries + 1):
        try:
            return client.messages.create(
                model=model,
                max_tokens=4096,
                messages=messages,
            )
        except anthropic.RateLimitError as e:
            if attempt == max_retries:
                raise
            wait = (2 ** attempt) * random.uniform(0.5, 1.5)
            print(f"Rate limited, waiting {wait:.1f}s...")
            time.sleep(wait)
        except anthropic.InternalServerError as e:
            if attempt == max_retries:
                raise
            wait = (2 ** attempt) * random.uniform(0.5, 1.5)
            time.sleep(wait)
        except anthropic.BadRequestError:
            raise  # Don't retry 400s

# Usage:
resp = call_with_retry([{"role": "user", "content": "Hello"}])

よくある質問

AI Prime Techは独立したAPIゲートウェイです。Anthropicとの提携関係はなく、同社の承認を受けておらず、同社の再販業者でもありません。Claudeおよび関連するモデル名は、それぞれの所有者の商標です。