code executionツールのエラーコード一覧とunavailable等の対処法
code executionツールが返すエラーコードを、bash・text_editorのサブツール別に一覧にします。unavailableやoutput_file_too_largeへの実装側の対処も扱います。
code executionツールのエラーはbash_code_execution_tool_result_errorのような専用のresult型で返り、error_codeフィールドに具体的な原因が入ります。全ツール共通のコードとbash固有・text_editor固有のコードが混在するため、サブツールごとに切り分けて対処法を押さえておく必要があります。
エラーレスポンスの形
すべてのエラーは、対応する_tool_resultのcontentが_error型に変わり、error_codeだけを持つ構造で返ります。
{
"type": "bash_code_execution_tool_result",
"tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR",
"content": {
"type": "bash_code_execution_tool_result_error",
"error_code": "unavailable"
}
}stdoutやstderrのような通常フィールドは無く、error_codeの文字列だけで原因を判定します。ここが、Bashコマンドが実行はされたが失敗した場合(return_codeが非ゼロでstderrにメッセージが入る通常のケース)との決定的な違いです。error_codeが返るのは、コマンドの実行そのものに到達できなかったケースを指します。両者を区別せずに「エラーかどうか」だけで分岐する実装だと、return_codeが非ゼロの通常の失敗(たとえばコマンドのタイプミス)と、ツール呼び出し自体が成立しなかったerror_codeつきの失敗を同じ経路で扱うことになり、原因の切り分けが難しくなります。エラーハンドリングを書くときは、まずcontent.typeが_resultか_result_errorかで最初の分岐を作るのが安全です。
Pythonでcontent.typeを見て_result_errorかどうかを判定し、error_codeをリトライ可否の2グループに振り分ける例です。
for block in response.content:
if block.type == "bash_code_execution_tool_result":
result = block.content
if result["type"] == "bash_code_execution_tool_result_error":
code = result["error_code"]
if code in ("unavailable", "too_many_requests"):
retry_with_backoff() # 一時的な障害。指数バックオフで再試行
else:
# invalid_tool_input / output_file_too_large / file_not_found
# / execution_time_exceeded はリトライしても同じ結果
log_and_fix(code)
else:
handle_bash_result(result) # return_code・stdout・stderrを持つ通常の実行結果エラーコード一覧(ツール種別ごと)
| ツール | error_code | 意味 |
|---|---|---|
| 全ツール共通 | error_codeunavailable | 意味ツールが一時的に利用できない |
| 全ツール共通 | error_codeexecution_time_exceeded | 意味ツール呼び出しが最大実行時間を超過した |
| 全ツール共通 | error_codeinvalid_tool_input | 意味ツールへの入力パラメーターが不正 |
| 全ツール共通 | error_codetoo_many_requests | 意味ツール利用のレート制限超過 |
| bash | error_codeoutput_file_too_large | 意味コマンドの出力サイズが上限を超過した |
| text_editor | error_codefile_not_found | 意味表示・編集対象のファイルが存在しない(view/editの操作が対象) |
表の6行のうち4行はbash_code_executionとtext_editor_code_executionのどちらでも起こり得る共通エラー、残り2行はサブツール固有です。file_not_foundはviewやstr_replaceのように既存ファイルを前提にした操作でだけ発生し、create(新規作成)では意味を持ちません。
too_many_requestsとリソース上限の関係
too_many_requestsはツール利用のレート制限を超えたときのエラーです。code executionはBashコマンドと組み合わせて使われることが多いため、短時間に何度もツール呼び出しを重ねるエージェント設計だと発生しやすくなります。実行環境そのものにも上限があり、コンテナはメモリ5GiB・CPU1コア・ディスク5GiBのワークスペースストレージという固定リソースで動いています。この上限自体はtoo_many_requestsとは別の制約ですが、ループ処理で大量のコマンドを短時間に発行する実装だと両方の上限に同時に触れることがあるため、リトライを実装するときは単純な即時再試行ではなく、指数バックオフで間隔を空けるのが安全です。
unavailableへの対処 — コンテナの状態を疑う
unavailableは「一時的に利用できない」という抽象的な説明のため、実装側では単純なリトライで解消するケースと、コンテナ側の問題であるケースを区別する必要があります。特に紛らわしいのが、期限切れのコンテナをcontainerパラメーターに指定したリクエストです。コンテナは作成から30日で期限切れになり、期限切れのコンテナは復元できず、参照するとエラーになります。レスポンスに含まれるcontainerオブジェクトのexpires_atはこれより短いローリング値で、30日の上限そのものを示す値ではないため、expires_atだけを見て「まだ有効」と判断すると期限切れを見落とします。この場合はリトライではなく、containerパラメーターを外した新規リクエストで解決します。単純な一時障害としてのunavailableであれば、指数バックオフを挟んだ再試行が基本の対処です。
unavailable関連でもう1つ実務でハマりやすいのが、コンテナのワークスペーススコープです。コンテナはFiles APIと同じく、リクエストを発行したワークスペースに紐づきます。あるAPIキーで作成したコンテナのcontainer.idを、別のワークスペースのAPIキーを使うリクエストに渡しても再利用できません。マルチテナント構成でAPIキーをワークスペースごとに分けている場合、container.idをキャッシュやDBに保存して使い回す設計では、どのワークスペースのキーで発行されたコンテナかを一緒に記録しておく必要があります。
execution_time_exceededとpause_turnを混同しない
タイムアウト関連にはexecution_time_exceededというerror_codeのほかに、pause_turnという別系統のstop_reasonがあります。両者は似ていますが指しているものが違います。
execution_time_exceeded: 1回のツール呼び出しが最大実行時間を超えたときのエラー(error_code)pause_turn: 長時間実行中のターン全体をAPI側が一時停止したことを示すstop_reason。レスポンスをそのまま次のリクエストに渡せばClaudeは処理を継続できる
プログラム的ツール呼び出し(code_execution_20260120以降)を使っている場合はさらに、Pythonセルごとの90秒のウォールクロック制限があります。この制限を超えたセルは、エラーとしてではなくreturn_codeが非ゼロでdetection_timeoutというステータスメッセージを含む通常の実行結果として返ってきます。execution_time_exceededはツール呼び出し全体が上限を超えたときのエラーコードであるのに対し、セル単位のタイムアウトは正常応答の一種として扱われる、という違いを区別しておくと、エラーハンドリングの分岐を誤りません。
output_file_too_largeとinvalid_tool_inputの防ぎ方
output_file_too_largeはbashコマンドの標準出力・標準エラー出力が大きすぎるときに発生します。ログを大量に吐くコマンドや、巨大なCSVをそのままcatするような操作で起きやすいエラーです。対処としては、コマンド側でheadやtail、wc -lなどを併用して出力を絞り込むよう、システムプロンプトやツール定義の説明文で指示しておくのが実務的です。
invalid_tool_inputはツールへの入力パラメーターそのものが不正な場合に返ります。bash_code_executionのcommandやtext_editor_code_executionのpath・old_strといった入力値はいずれもClaude自身が組み立てる値で、アプリケーション側が渡すものではありません。したがってinvalid_tool_inputは実装側の入力ミスではなくモデルの出力側の問題であることが多く、アプリケーション側で個別に予防できる性質のエラーではありません。頻発する場合はモデルのバージョンやツール定義側の見直しが優先です。
レガシーツールバージョンからの移行でパースが壊れることがある
error_codeそのものとは別に、実装側が見落としやすいのがツールバージョンの違いによるレスポンス型の変化です。旧式のcode_execution_20250522(Python専用)は結果をcode_execution_resultという単一の型で返していましたが、code_execution_20250825以降はBashコマンドとファイル操作が分離され、bash_code_execution_resultとtext_editor_code_execution_*_resultという別々の型になりました。エラー型も同様に、旧バージョンの型名を前提にレスポンスをパースする実装をそのまま新しいツールバージョンに向けると、error_codeを含むエラーレスポンス自体を正しく認識できず、原因不明の例外として扱われてしまいます。ツールバージョンを更新した直後にエラーハンドリングが動かなくなった場合は、まずレスポンスの型名を新しい命名規則(bash_code_execution_tool_result_error / text_editor_code_execution_tool_result_error)に合わせているかを確認してください。
file_not_foundが起きやすい状況
file_not_foundはtext_editor_code_executionのviewやstr_replaceのように、既存ファイルの存在を前提にした操作でだけ発生します。実務でこのエラーに当たるのは、たいてい次のいずれかです。
- パスの取り違え(相対パスと絶対パスの混同、あるいはコンテナ内の別ディレクトリに実際は保存されている)
- コンテナをまたいだ参照: 前回のリクエストで作ったファイルを、
containerパラメーターを指定せずに新規コンテナで開始した次のリクエストから参照しようとしている(明示的にcontainer.idを渡さない限り、前回のコンテナの中身は引き継がれません) createより先にviewやstr_replaceを呼んでいる(まだ存在しないファイルを編集しようとしている)
2つ目のパターンは、$OUTPUT_DIRの罠で扱ったコンテナ再利用の話と表裏の関係にあります。コンテナを再利用したいならcontainer.idを明示的に渡す、これを怠ると新しい空のコンテナから開始され、以前作ったファイルはすべてfile_not_foundの対象になります。
bashツール(クライアントツール)のエラーとの違い
code executionのエラーはerror_codeという専用フィールドで返る一方、bashツール(クライアント側で実行するツール)にはこの仕組みがありません。bashツールはあなたのアプリケーションが実行するため、コマンドが失敗したとき何をClaudeに伝えるかは実装側の裁量です。公式サンプルでは、tool_resultのcontentにエラーメッセージの文字列を入れ、is_error: trueを立てる形で「ツール呼び出しが失敗した」ことを伝えます。
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: command did not finish within 30 seconds",
"is_error": true
}code executionはAnthropic側のサンドボックスで実行されるためerror_codeという構造化された形でエラーが返るのに対し、bashツールはクライアント側の実装がエラーの伝え方そのものを決める、という非対称性があります。code executionとbashツールを併用する構成では、この2つのエラー通知の仕組みが異なることも踏まえてハンドリングを分ける必要があります。両ツールを同時に使う際に生じる別の落とし穴(実行環境の混同)はcode executionとbashツールの併用で混同する実行環境にまとめています。
リトライすべきか・実装を直すべきかの分岐
6種類のエラーコードは、対処の方向性で2つのグループに分かれます。unavailableとtoo_many_requestsは一時的な状態が原因なので、指数バックオフを挟んだリトライで解消することが多いエラーです。一方invalid_tool_input・output_file_too_large・file_not_found・execution_time_exceededは、同じ入力を投げ直しても同じ結果にしかならない性質のエラーで、リトライではなくプロンプトやツール定義側の見直しが必要になります。エラーハンドリングを実装する際は、この2グループを最初に切り分けておくと、無駄なリトライループや、逆に直すべき箇所を直さずリトライだけを重ねてしまう事故を防げます。
まとめ
code executionのエラーはerror_codeという専用フィールドで返り、全ツール共通の4種類(unavailable/execution_time_exceeded/invalid_tool_input/too_many_requests)と、bash固有のoutput_file_too_large、text_editor固有のfile_not_foundに分かれます。同じくerror_codeで構造化されたエラーを持つツールとしてはweb searchツールのエラーコード一覧もあり、コード体系自体は別物ですが分岐の考え方は共通します。unavailableはコンテナの期限切れを疑い、execution_time_exceededはpause_turnやセル単位のタイムアウトと混同しない、という2点が実装時に迷いやすいポイントです。MCPツールをコードとして呼び出す設計は同じサンドボックスの上に成り立っており、そちら側の実装パターンはMCPをコードとして呼び出す設計で扱っています。ツール数自体を絞ってエラー要因を減らす選択肢はTool Search Tool等の3ベータで扱っています。