code executionツールのエラーコード一覧とunavailable等の対処法

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_code_execution_resultで、return_codeが非ゼロになりstderrにメッセージが入ります。error_codeが返るのは、コマンドの実行そのものに到達できなかったケースです。

この2つを「エラーかどうか」だけで分岐すると、コマンドのタイプミスのような通常の失敗と、ツール呼び出しが成立しなかった失敗が同じ経路に入ります。最初の分岐はcontent.typeが_resultか_result_errorかで作ります。

サーバー側で動くツールのエラーは、クライアントツールとは扱いが違います。ツール呼び出しを説明するページによると、Web検索などのサーバーツールでエラーが起きると、Claudeが代替の応答や説明を試みます。そのためクライアントツールのようにis_errorの結果を返す処理は要りません。アプリケーション側でエラーを拾う目的は、ログと再試行の判断です。

Pythonで、先ほどの2グループに沿ってerror_codeを振り分ける例です。

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を持つ通常の実行結果

エラーコード一覧(ツール種別ごと)

6行のうち4行はbash_code_executionとtext_editor_code_executionのどちらでも起こり得る共通エラーで、残り2行がサブツール固有です。file_not_foundはviewやstr_replaceのように既存ファイルを前提にした操作が対象で、create(新規作成)は、既存ファイルを前提にしないため対象外と考えられます。web searchツールのエラーもerror_codeで返りますが、コード体系は別です。比べるならweb searchツールのエラーコード一覧が参考になります。

too_many_requestsとリソース上限

too_many_requestsはツール利用のレート制限を超えたときのエラーです。短時間にツール呼び出しを重ねるエージェント設計では、この上限に近づきます。再試行は即時ではなく、指数バックオフで間隔を空ける実装が無難です。

実行環境の上限はレート制限とは別に決まっています。コンテナはメモリ5GiB、CPU1コア、ワークスペースのディスク5GiBで動きます。エラーコードの表にはメモリやディスクの超過に対応するコードがありません。時間の超過だけがexecution_time_exceededとして表に載っています。

unavailableとコンテナの期限

unavailableは「一時的に利用できない」という説明だけで、原因までは分かりません。コンテナの寿命は別の話ですが、期限の仕組みを知っておくと、再利用まわりの失敗を切り分けられます。

期限切れのコンテナを指定した場合の返り方について、公式は「エラーを返す」としか書いておらず、error_codeが何になるかは表に載っていません。unavailableとして返ると決めつけず、レスポンスのerror_codeを読んで判断します。対処は共通です。containerパラメーターを外して、新規コンテナで送り直します。

ワークスペース単位の紐づけは、マルチテナント構成に響きます。コンテナはリクエストのワークスペースに紐づくため、別ワークスペースのAPIキーでは同じcontainer.idを使えない前提で設計します。IDをキャッシュやDBに保存して使い回す設計では、どのワークスペースのキーで発行したかを一緒に記録します。

単純な一時障害としてのunavailableなら、指数バックオフを挟んだ再試行が基本です。このサンドボックスの上でMCPツールをコードとして呼び出す設計は、MCPをコードとして呼び出す設計で扱っています。

execution_time_exceededとpause_turnを混同しない

タイムアウトに関わる仕組みは3つあり、返り方がそれぞれ違います。

• execution_time_exceeded: 1回のツール呼び出しが最大実行時間を超えたときのerror_code
• pause_turn: 長時間実行中のターン全体をAPI側が一時停止したことを示すstop_reason。レスポンスをそのまま次のリクエストに渡せば、Claudeは処理を継続する。内容を変えて渡せば、会話を中断する選択もできる
• セル単位の90秒制限: プログラム的ツール呼び出しで、Pythonの各セルに掛かるウォールクロックの制限

セルが90秒を超えると、エラーではなく、return_codeが非ゼロで出力にdetection_timeoutというステータスメッセージを含む通常の実行結果が返ります。この制限をClaudeに伝えるのはcode_execution_20260521のツール説明です。code_execution_20260120と同じランタイムで、Claudeが長いセルの時間配分を考えられるようになります。

エラーハンドリングの分岐は、error_code、return_code、stop_reasonの3か所を別々に見て作ります。

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が組み立てる値です。アプリケーションが渡す値ではありません。ログで傾向を見て、プロンプトやツール定義の側を見直します。

頻発するなら、ログに入力の中身を残します。ツールの数が多すぎて選び間違いが起きている場合は、Tool Search Tool等の3ベータのようにツール数を絞る選択肢もあります。

ツールバージョンを上げたときのパース

error_codeとは別に、ツールバージョンの違いでレスポンス型が変わる点にも注意が要ります。旧式のcode_execution_20250522はPython専用で、結果はcode_execution_resultという型で返っていました。code_execution_20250825以降はBashコマンドとファイル操作が分かれ、bash_code_execution_resultとtext_editor_code_execution_*_resultの型になります。ベータヘッダー(code-execution-2025-05-22)も、現行のバージョンでは不要です。

Pythonだけを使う既存の処理は、旧バージョンのまま動き続けます。切り替えるときは、typeの文字列を差し替えたうえで、レスポンスをプログラムで解釈している部分を見直します。現行のバージョンは3つあり、code_execution_20260521が最新です。

旧バージョンのエラー型の名前は、移行のページに載っていません。型名を固定の文字列で突き合わせている実装は、切り替え後にerror_codeつきのエラーを取りこぼす恐れがあります。_tool_result_errorで終わるかどうかで判定すれば、サブツールが増えても同じコードで拾えます。

file_not_foundが起きる状況

file_not_foundはtext_editor_code_executionのviewやstr_replaceなど、既存ファイルを前提にした操作で返ります。原因として考えられるのは、次の3つです。

• パスの取り違え(相対パスと絶対パスの混同、コンテナ内の別ディレクトリへの保存)
• コンテナをまたいだ参照: 各リクエストは、前回のレスポンスのコンテナ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
}

2つのツールを併用する構成では、エラーの伝わり方が違う前提でハンドリングを分けます。両ツールを同時に使うときのもう1つの落とし穴、実行環境の混同はcode executionとbashツールの併用で混同する実行環境にまとめています。

まとめ

分岐の入口はcontent.typeで、error_codeが返るのは実行に届かなかったときだけです。ログにはerror_codeに加えて、使っていたサブツール、container.id、リクエストのワークスペースを残します。file_not_foundと期限切れコンテナの切り分けは、この3つがあれば追えます。