Claude APIのエラー

HTTPエラー

APIは予測可能なHTTPエラーコード形式に従います。

• 400 - invalid_request_error：リクエストの形式または内容に問題がありました。このエラータイプは、このセクションに記載されていない他の4XXステータスコードにも使用される場合があります。また、使用量が組織またはワークスペースに設定した支出制限に達した場合にもAPIは400を返します。ただし、Claude Codeワークスペースの制限は例外で、代わりに429を返すことがあります。

• 401 - authentication_error：APIキーに問題があります（例えば、形式が不正、取り消し済み、または期限切れ。キーの有効期限を参照してください）。Claude Platform on AWSでは、AWS認証情報またはSigV4署名の問題を示している場合もあります。

• 402 - billing_error：請求または支払い情報に問題があります。Claude Consoleで支払い情報を確認してください。Claude Platform on AWSを使用している場合はAWS Marketplaceで確認してください。

• 403 - permission_error：APIキーに指定されたリソースを使用する権限がありません。Claude Consoleで組織のアクセス権とワークスペース設定を確認してください。

• 404 - not_found_error：要求されたリソースが見つかりませんでした。エンドポイントのパスとリクエストURL内のリソースIDを確認してください。

• 409 - conflict_error：リクエストがリソースの現在の状態と競合しています。例えば、リソースが同時に変更された、または一意でなければならない値がすでに使用されている場合です。競合を解決してから、リクエストを再試行してください。

• 413 - request_too_large：リクエストが許可される最大バイト数を超えています。エンドポイントごとの上限についてはリクエストサイズ制限を参照してください。

• 429 - rate_limit_error：組織が「rate limit」（レート制限）に達した、使用量ティアの月間支出上限に達した、またはClaude Codeワークスペースの支出制限に達しました。詳細はレート制限を参照してください。ティアの支出上限による429にはretry-afterヘッダーがなく、アクセスが再開されるまで失敗し続けます。見分け方については支出上限への到達を参照してください。

• 500 - api_error：Anthropicのシステム内部で予期しないエラーが発生しました。指数バックオフでリクエストを再試行してください。エラーが続く場合は、リクエストIDを添えてサポートにお問い合わせください。

• 504 - timeout_error：処理中にリクエストがタイムアウトしました。長時間実行されるリクエストにはストリーミングMessages APIの使用を検討してください。その他のオプションについては長時間のリクエストを参照してください。

• 529 - overloaded_error：APIが一時的に過負荷状態です。

公式SDKは、一時的な障害（接続エラー、レート制限、5xxサーバーエラーなど）を指数バックオフで自動的に再試行します。デフォルトでは2回再試行し、retry-afterヘッダーが存在する場合はそれに従います。各SDKクライアントは、この動作を設定または無効化するための最大再試行回数オプションを受け付けます。

server-sent events（SSE）経由で「streaming」（ストリーミング）レスポンスを受信する場合、APIが200レスポンスを返した後にエラーが発生することがあります。その場合、エラー処理はこれらの標準的なメカニズムに従いません。ストリーム途中のエラーの形式については、ストリーミングのエラーイベントを参照してください。

リクエストサイズ制限

APIはリクエストサイズ制限を適用します。

これらの制限を超えると、413 request_too_largeエラーが返されます。直接のClaude APIでは、リクエストがAPIサーバーに到達する前にCloudflareがこのエラーを返します。

エラーの形式

APIは常にエラーをJSONとして返します。トップレベルのerrorオブジェクトには常にtypeとmessageの値が含まれます。レスポンスには、追跡とデバッグを容易にするためのrequest_idフィールドも含まれます。例：

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested resource could not be found."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

バージョニングポリシーに従い、これらのオブジェクト内の値は拡張される可能性があり、typeの値が時間とともに増える可能性があります。

SDKのエラー型

公式SDKは、これらのエラーに対して生のJSONを返す代わりに型付き例外を発生させます。クラス名と名前空間は言語によって異なります。例えば、404はPythonではanthropic.NotFoundError、RubyではAnthropic::Errors::NotFoundError、Javaではcom.anthropic.errors.NotFoundException、Goでは単一の*anthropic.Error値（StatusCodeで分岐）として表面化します。エラーメッセージの文字列マッチングではなくSDKの型付きクラスをキャッチし、最も具体的なクラスから順に処理してください。各SDKページに完全な例外階層が記載されています。

• Python · TypeScript · C# · Go · Java · PHP · Ruby

リクエストID

すべてのAPIレスポンスには一意のrequest-idヘッダーが含まれます。このヘッダーにはreq_018EeWyXxfu5pfWkrYcMdjWGのような値が含まれます。同じ識別子がエラーレスポンス本文のrequest_idフィールドにも表示されます。特定のリクエストについてサポートに問い合わせる際は、問題を迅速に解決できるようこのIDを含めてください。

Claude Platform on AWSでは、レスポンスに2つのリクエストIDが含まれます。AWSリクエストID（x-amzn-requestid、プライマリ、CloudTrailでインデックス化）とAnthropicリクエストID（request-id、セカンダリ）です。CloudTrailの検索にはAWSリクエストIDを、AnthropicのサポートチケットにはAnthropicリクエストIDを使用してください。

PythonおよびTypeScript SDKは、トップレベルのレスポンスオブジェクトの_request_idプロパティとしてリクエストIDを公開します。C#、Go、Java、PHP SDKは生レスポンスアクセサーを通じて、Ruby SDKはミドルウェアを通じて公開します。同じメカニズム、およびPythonのwith_raw_responseとTypeScriptの.withResponse()は、anthropic-organization-idやanthropic-workspace-idなど、他のレスポンスヘッダーも読み取ります。Claude Platform on AWSでは、生レスポンスアクセサーを使用してAWSリクエストID（x-amzn-requestid）も読み取ります。

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(f"Request ID: {message._request_id}")

他の言語でのClaude Platform on AWSのリクエストIDの例については、リクエストIDを参照してください。

長時間のリクエスト

ストリーミングMessages APIまたはMessage Batches APIを使用せずに、大きなmax_tokens値を設定することは避けてください。

• 一部のネットワークでは、一定ではない時間が経過するとアイドル接続が切断されることがあり、 Anthropicからレスポンスを受信することなくリクエストが失敗またはタイムアウトする原因となる可能性があります。
• ネットワークの信頼性はそれぞれ異なります。Message Batches APIは、 中断のないネットワーク接続を必要とせず、結果をポーリングできるようにすることで、ネットワーク問題のリスク管理に役立ちます。

直接API統合を構築している場合、TCPソケットキープアライブを設定すると、一部のネットワークでアイドル接続タイムアウトの影響を軽減できます。

SDKは、非ストリーミングのMessages APIリクエストが10分のタイムアウトを超えないと見込まれることを検証します。また、TCPキープアライブのソケットオプションも設定します。

イベントを段階的に処理する必要がない場合、SDKがストリームを消費し、非ストリーミング呼び出しが返すものと同一の完全なMessageオブジェクトを返すことができます。

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=128000,
    messages=[{"role": "user", "content": "Write a detailed analysis..."}],
    model="claude-sonnet-5",
) as stream:
    message = stream.get_final_message()

print(next(block.text for block in message.content if block.type == "text"))

詳細についてはストリーミングメッセージを参照してください。

よくあるバリデーションエラー

プリフィルはサポートされていません

Claude 4.6以降のモデルおよびClaude Mythos Previewは、アシスタントメッセージのプリフィルをサポートしていません。これらのモデルのいずれかに、最後のアシスタントメッセージをプリフィルしたリクエストを送信すると、400 invalid_request_errorが返されます。

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "This model does not support assistant message prefill. The conversation must end with a user message."
  }
}

代わりに、サポートしているモデルでは構造化出力、システムプロンプトの指示、またはoutput_config.formatを使用してください。

thinkingブロックは変更できません

最新のアシスタントメッセージに、APIに送り返される前に編集、並べ替え、除外、または再構築されたthinkingまたはredacted_thinkingブロックが含まれている場合、リクエストは400 invalid_request_errorを返します。エラーメッセージは問題のあるブロックの位置（例：messages.1.content.0）で始まり、次の内容を含みます。

`thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified. These blocks must remain as they were in the original response.

「tool use」（ツール使用）では、アシスタントターンのすべてのthinkingおよびredacted_thinkingブロックを、thinkingフィールドが空のブロックも含めて、受信したとおりに正確に渡し返す必要があります。thinkingブロックは変更せずに渡し返してください。アプリケーションが再送信前にコンテンツブロックをタイプでフィルタリングする場合は、thinkingとredacted_thinkingの両方を含めてください。思考のトラブルシューティング、thinkingブロックの保持、および保持された思考を参照してください。

拡張思考はサポートされていません

Claude 4.7以降のモデルでは「extended thinking」（拡張思考）が削除されました。これらのモデルのいずれかにthinking: {"type": "enabled"}を送信すると、400 invalid_request_errorが返されます。

"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

代わりに適応型思考を使用してください。適応型思考への移行にパラメータの対応関係が示されており、思考のトラブルシューティングでは症状から始める修正方法を説明しています。

適応型思考はサポートされていません

拡張思考のみをサポートするモデル（Claude 4.5以前のモデル）は、thinking: {"type": "adaptive"}を400 invalid_request_errorで拒否します。

adaptive thinking is not supported on this model

これらのモデルではthinking: {"type": "enabled", "budget_tokens": N}を使用してください。設定については拡張思考を、症状から始める修正方法については思考のトラブルシューティングを参照してください。

思考を無効にできません

Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5、Claude Mythos 5、およびClaude Mythos Previewでは、思考は常に有効です。これらのモデルのいずれかにthinking: {"type": "disabled"}を送信すると、400 invalid_request_errorが返されます。Claude Mythos Previewを除くこれらすべてのモデルでは、メッセージは次のようになります。

"thinking.type.disabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

これらのモデルの中で唯一拡張思考を受け付けるClaude Mythos Previewでは、メッセージは次のようになります。

"thinking.type.disabled" is not supported for this model. Thinking defaults to adaptive mode when not specified; use "thinking.type.enabled" with "budget_tokens" for extended thinking.

thinkingパラメータを省略すると、リクエストは適応型思考で実行されます。思考を無効にせずにレスポンスから思考内容を除外するには、思考の設定でdisplay: "omitted"を設定してください。思考のトラブルシューティングを参照してください。

強制ツール使用はサポートされていません

Claude Fable 5.1およびClaude Mythos 5.1は強制ツール使用をサポートしていません。いずれかのモデルにtool_choice: {"type": "any"}またはtool_choice: {"type": "tool", "name": "..."}を送信すると、トークンカウントエンドポイントを含め、400 invalid_request_errorが返されます。

tool_choice: type "tool" and "any" are not supported for this model.

tool_choice: {"type": "auto"}（デフォルト）と{"type": "none"}は受け付けられます。ツール入力をスキーマに準拠させるにはautoを厳密なツール使用と組み合わせて使用し、レスポンス自体を固定のJSON形式にする必要がある場合は構造化出力を使用してください。ツール使用の強制を参照してください。

thinkingブロックが会話と一致しなくなりました

Claude Fable 5.1では、APIは再送されたthinkingブロックを、それに先行するsystemプロンプト、tools、およびメッセージが変更されていない間のみ受け付けます。2026年8月31日以降に作成された新規アカウント、およびthinking.block_binding.prefix_mismatch_behaviorを"error"に設定したすべてのリクエストでは、以前の履歴が変更された再送ブロックは400 invalid_request_errorで拒否されます（"drop_block"の場合、APIはブロックを破棄し、リクエストは成功します）。メッセージは最初に失敗したブロックの位置で始まります。

messages.{i}.content.{j}: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block".

thinking-binding-controls-2026-08-01ベータヘッダーがない場合、メッセージにはそのヘッダー名も含まれます。会話履歴を追記のみにするか、ベータヘッダーをprefix_mismatch_behavior: "drop_block"とともに送信してブロックを破棄し、処理を続行してください。対象モデルが読み取れないモデルからのブロックは、拒否されるのではなく破棄されます。プレフィックスを変更しないようにするおよび思考のトラブルシューティングを参照してください。

thinking-binding-controls-2026-08-01ベータヘッダーなしでthinking.block_bindingを送信すると、メッセージが次の内容で終わる400 invalid_request_errorが返されます。

block_binding: Extra inputs are not permitted

ヘッダーを追加するか、フィールドを削除してください。

アウトバウンドWeb IDフェデレーションが無効（Claude Platform on AWS）

Claude Platform on AWSへのすべてのリクエストが"Outbound web identity federation is disabled for your account"を返す場合は、AWSアカウントごとに1回aws iam enable-outbound-web-identity-federationを実行してください。詳細についてはアウトバウンドWeb IDフェデレーションの有効化を参照してください。

次のステップ