Use TimeoutError for confirmed sandbox-killed errors

Matches the existing 502 mapping in extractError/extract_exception and
the base SDK convention: a dead sandbox surfaces as TimeoutError /
TimeoutException. When the health probe is inconclusive or the sandbox
is still running, the original transport error propagates unchanged.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: mishushakov

.changeset/grumpy-sloths-relax.md

@@ -3,4 +3,4 @@
 '@e2b/code-interpreter-python': patch
 ---
 
-Throw a descriptive sandbox error instead of a raw socket error (e.g. `ECONNRESET`) when the sandbox is killed or times out while a request (`runCode`/`run_code`, context management) is in progress
+Throw a descriptive `TimeoutError`/`TimeoutException` instead of a raw socket error (e.g. `ECONNRESET`) when the sandbox is killed or times out while a request (`runCode`/`run_code`, context management) is in progress

js/src/sandbox.ts

@@ -1,4 +1,4 @@
-import { Sandbox as BaseSandbox, InvalidArgumentError, SandboxError } from 'e2b'
+import { Sandbox as BaseSandbox, InvalidArgumentError, TimeoutError } from 'e2b'
 
 import {
   Result,
@@ -435,7 +435,7 @@ export class Sandbox extends BaseSandbox {
   }
 
   /**
-   * Throws a descriptive `SandboxError` if the connection error was caused
+   * Throws a descriptive `TimeoutError` if the connection error was caused
    * by the sandbox being killed mid-request. If the sandbox is still running
    * (or its state can't be determined), returns so the caller can re-throw
    * the original error.
@@ -448,7 +448,7 @@ export class Sandbox extends BaseSandbox {
       // original error instead of wrongly claiming the sandbox is gone.
       (await this.isRunning().catch(() => true)) === false
     ) {
-      throw new SandboxError(
+      throw new TimeoutError(
         'The sandbox was killed while the request was in progress. This can happen when the sandbox times out or is killed manually. ' +
           "You can modify the sandbox timeout by passing 'timeoutMs' when starting the sandbox or calling '.setTimeout' on the sandbox with the desired timeout."
       )

js/tests/killedSandbox.test.ts

@@ -1,3 +1,4 @@
+import { TimeoutError } from 'e2b'
 import { expect } from 'vitest'
 
 import { isDebug, sandboxTest, wait } from './setup'
@@ -6,9 +7,12 @@ sandboxTest.skipIf(isDebug)(
   'runCode throws a descriptive error when the sandbox is killed during execution',
   async ({ sandbox }) => {
     const execution = sandbox.runCode('import time; time.sleep(60)')
-    const assertion = expect(execution).rejects.toThrowError(
-      /sandbox was killed while the request was in progress/
-    )
+    const assertion = Promise.all([
+      expect(execution).rejects.toThrowError(
+        /sandbox was killed while the request was in progress/
+      ),
+      expect(execution).rejects.toBeInstanceOf(TimeoutError),
+    ])
 
     await wait(2_000)
     await sandbox.kill()

python/e2b_code_interpreter/exceptions.py

@@ -1,4 +1,4 @@
-from e2b import SandboxException, TimeoutException
+from e2b import TimeoutException
 
 
 def format_request_timeout_error() -> Exception:
@@ -14,7 +14,7 @@ def format_execution_timeout_error() -> Exception:
 
 
 def format_sandbox_killed_error() -> Exception:
-    return SandboxException(
+    return TimeoutException(
         "The sandbox was killed while the request was in progress. This can happen when the sandbox times out or is killed manually. "
         "You can modify the sandbox timeout by passing 'timeout' when starting the sandbox or calling '.set_timeout' on the sandbox with the desired timeout",
     )

python/tests/async/test_async_killed.py

@@ -2,7 +2,7 @@
 
 import pytest
 
-from e2b import SandboxException
+from e2b import TimeoutException
 from e2b_code_interpreter import AsyncSandbox
 
 
@@ -18,6 +18,6 @@ async def test_run_code_raises_when_sandbox_is_killed_during_execution(
     await async_sandbox.kill()
 
     with pytest.raises(
-        SandboxException, match="sandbox was killed while the request was in progress"
+        TimeoutException, match="sandbox was killed while the request was in progress"
     ):
         await execution

python/tests/sync/test_killed.py

@@ -2,7 +2,7 @@
 
 import pytest
 
-from e2b import SandboxException
+from e2b import TimeoutException
 from e2b_code_interpreter import Sandbox
 
 
@@ -13,7 +13,7 @@ def test_run_code_raises_when_sandbox_is_killed_during_execution(sandbox: Sandbo
 
     try:
         with pytest.raises(
-            SandboxException,
+            TimeoutException,
             match="sandbox was killed while the request was in progress",
         ):
             sandbox.run_code("import time; time.sleep(60)")