Error handling

Common errors

Error	Where it appears	Description	Solution
invalid_tool_input	error_code on the code_execution_tool_result error block in the response	Invalid parameters were passed to the code execution tool	See the code execution tool errors
invalid_request_error (on tool_choice)	HTTP 400 error response	tool_choice names a tool whose allowed_callers does not include "direct"	Either add "direct" to that tool's allowed_callers, or remove the tool from tool_choice and let Claude invoke it from code

Container expiration during tool call

If your tool result doesn't arrive within about 4 minutes, the pending call raises a TimeoutError inside Claude's running code. Claude sees the error in stderr and typically retries the call:

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "code_execution_result",
    "stdout": "",
    "stderr": "TimeoutError: Calling tool ['query_database'] timed out (no response after 270s).",
    "return_code": 0,
    "content": []
  }
}

To prevent timeouts:

• Monitor the expires_at field in responses
• Implement timeouts for your tool execution
• Consider breaking long operations into smaller chunks

Tool execution errors

If your tool returns an error:

{
  "type": "tool_result",
  "tool_use_id": "toolu_abc123",
  "content": "Error: Query timeout - table lock exceeded 30 seconds"
}

Claude's code receives this error and can handle it appropriately.