docs: sandbox behavior during lifecycle transitions

docs/sandbox.mdx

@@ -84,8 +84,8 @@
 //   "templateId": "rki5dems9wqfm4r03t7g",
 //   "name": "base",
 //   "metadata": {},
 //   "startedAt": "2025-03-24T15:37:58.076Z",
 //   "endAt": "2025-03-24T15:42:58.076Z"
 // }
 ```
 
@@ -134,3 +134,5 @@
 sandbox.kill()
 ```
 </CodeGroup>
+
+For details on how the SDK handles operations during state transitions (pause, resume, kill) and a reference of possible errors, see [Behavior during state transitions](/docs/sandbox/persistence#behavior-during-state-transitions).

docs/sandbox/auto-resume.mdx

@@ -66,6 +66,8 @@
 
 If a sandbox is paused and `autoResume` is enabled, the next supported operation resumes it automatically. You do not need to call [`Sandbox.connect()`](/docs/sandbox/connect) first.
 
+When auto-resume triggers, the SDK handles the resume transparently — if the sandbox is mid-transition, operations wait for the transition to complete. See [Behavior during state transitions](/docs/sandbox/persistence#behavior-during-state-transitions) for the full error reference.
+
 ### SDK example: pause, then read a file
 
 <CodeGroup>
@@ -152,7 +154,7 @@
 
 await new Promise((resolve) => setTimeout(resolve, 1000))
 
 const previewHost = sandbox.getHost(3000)
 console.log(`Preview URL: https://${previewHost}`)
 
 console.log(`Status before pause: ${(await sandbox.getInfo()).state}`)
@@ -254,7 +256,7 @@
 ```js JavaScript & TypeScript
 import { Sandbox } from 'e2b'
 
 const userSandboxes = new Map() // userId → Sandbox
 
 async function getSandbox(userId) {
   let sandbox = userSandboxes.get(userId)

docs/sandbox/connect.mdx

@@ -13,20 +13,20 @@
 ```js JavaScript & TypeScript
 import { Sandbox } from '@e2b/code-interpreter'
 
 const sbx = await Sandbox.create()
 
 // Get all running sandboxes
 const paginator = await Sandbox.list({
   query: { state: ['running'] },
 })
 
 const runningSandboxes = await paginator.nextItems()
 if (runningSandboxes.length === 0) {
   throw new Error('No running sandboxes found')
 }
 
 // Get the ID of the sandbox you want to connect to
 const sandboxId = runningSandboxes[0].sandboxId
 ```
 
 ```python Python
@@ -74,3 +74,5 @@
 print(f"Running in sandbox {sandbox.sandbox_id} as \"{r.stdout.strip()}\"")
 ```
 </CodeGroup>
+
+If the sandbox is paused, `Sandbox.connect()` automatically resumes it before returning. If the sandbox is mid-transition (for example, currently pausing), the SDK waits for the transition to complete. See [Behavior during state transitions](/docs/sandbox/persistence#behavior-during-state-transitions) for details and error handling.

docs/sandbox/persistence.mdx

@@ -69,6 +69,81 @@
 ```
 </CodeGroup>
 
+## Behavior during state transitions
+
+Lifecycle operations like `pause()`, `connect()`, and `kill()` can take a variable amount of time to complete — pausing, for example, takes approximately 4 seconds per GiB of RAM. If you call an SDK operation while a sandbox is mid-transition, the SDK automatically waits for the transition to finish and then executes your operation. From your code's perspective, the transition appears instant.
+
+<Note>
+You do not need to poll sandbox state or add retry logic around transitions. The SDK handles waiting for you.
+</Note>
+
+Here's what happens in specific scenarios:
+
+| Scenario | What the SDK does |
+|---|---|
+| Call `commands.run()` while sandbox is pausing | Waits for pause to complete, then resumes the sandbox, then runs the command |
+| Call `connect()` on a paused sandbox | Automatically resumes the sandbox and returns a connected instance |
+| Call `connect()` on an already-running sandbox | Connects immediately — no state change needed |
+| Call `kill()` from any state | Transitions the sandbox to Killed, regardless of current state |
+| Call `pause()` on an already-paused sandbox | Returns immediately — no-op |
+
+### Errors during lifecycle operations
+
+When a lifecycle operation fails, the SDK raises one of the following errors. This table covers the most common cases — see the full error reference for [JavaScript](/docs/sdk-reference/js-sdk/v2.14.1/errors) and [Python](/docs/sdk-reference/python-sdk/v2.9.1/exceptions).
+
+| Operation | Error (JS / Python) | When it occurs |
+|---|---|---|
+| `pause()` | `NotFoundError` / `NotFoundException` | Sandbox doesn't exist or was already killed |
+| `connect()` | `NotFoundError` / `NotFoundException` | Sandbox ID doesn't exist |
+| `connect()` | `TimeoutError` / `TimeoutException` | Resume didn't complete within the timeout window |
+| `kill()` | `NotFoundError` / `NotFoundException` | Sandbox doesn't exist |
+| Any operation during a transition | `TimeoutError` / `TimeoutException` | The transition plus the operation together exceeded the request timeout |
+
+Here's an example of handling errors during lifecycle operations:
+
+<CodeGroup>
+```js JavaScript & TypeScript
+import { Sandbox, TimeoutError, NotFoundError } from '@e2b/code-interpreter'
+
+const sbx = await Sandbox.create()
+const sandboxId = sbx.sandboxId
+
+await sbx.pause()
+
+try {
+  // connect() automatically resumes a paused sandbox
+  const resumed = await Sandbox.connect(sandboxId)
+  const result = await resumed.commands.run('echo hello')
+  console.log(result.stdout)
+} catch (error) {
+  if (error instanceof NotFoundError) {
+    console.error('Sandbox no longer exists:', error.message)
+  } else if (error instanceof TimeoutError) {
+    console.error('Operation timed out during transition:', error.message)
+  }
+}
+```
+```python Python
+from e2b_code_interpreter import Sandbox
+from e2b import TimeoutException, NotFoundException
+
+sbx = Sandbox.create()
+sandbox_id = sbx.sandbox_id
+
+sbx.pause()
+
+try:
+    # connect() automatically resumes a paused sandbox
+    resumed = Sandbox.connect(sandbox_id)
+    result = resumed.commands.run("echo hello")
+    print(result.stdout)
+except NotFoundException as e:
+    print(f"Sandbox no longer exists: {e}")
+except TimeoutException as e:
+    print(f"Operation timed out during transition: {e}")
+```
+</CodeGroup>
+
 ## Pausing sandbox
 When you pause a sandbox, both the sandbox's filesystem and memory state will be saved. This includes all the files in the sandbox's filesystem and all the running processes, loaded variables, data, etc.
 
@@ -76,7 +151,7 @@
 ```js JavaScript & TypeScript highlight={8-9}
 import { Sandbox } from '@e2b/code-interpreter'
 
 const sbx = await Sandbox.create()
 console.log('Sandbox created', sbx.sandboxId)
 
 // Pause the sandbox
@@ -106,7 +181,7 @@
 ```js JavaScript & TypeScript highlight={12-13}
 import { Sandbox } from '@e2b/code-interpreter'
 
 const sbx = await Sandbox.create()
 console.log('Sandbox created', sbx.sandboxId)
 
 // Pause the sandbox
@@ -115,7 +190,7 @@
 console.log('Sandbox paused', sbx.sandboxId)
 
 // Connect to the sandbox (it will automatically resume the sandbox, if paused)
 const sameSbx = await sbx.connect()
 console.log('Connected to the sandbox', sameSbx.sandboxId)
 ```
 ```python Python highlight={12-13}
@@ -144,7 +219,7 @@
 import { Sandbox, SandboxInfo } from '@e2b/code-interpreter'
 
 // List all paused sandboxes
 const paginator = Sandbox.list({ query: { state: ['paused'] } })
 
 // Get the first page of paused sandboxes
 const sandboxes = await paginator.nextItems()
@@ -179,7 +254,7 @@
 ```js JavaScript & TypeScript highlight={11,14}
 import { Sandbox } from '@e2b/code-interpreter'
 
 const sbx = await Sandbox.create()
 console.log('Sandbox created', sbx.sandboxId)
 
 // Pause the sandbox
@@ -215,7 +290,7 @@
 ```js JavaScript & TypeScript
 import { Sandbox } from '@e2b/code-interpreter'
 
 const sbx = await Sandbox.connect(sandboxId, { timeoutMs: 60 * 1000 }) // 60 seconds
 ```
 ```python Python
 from e2b_code_interpreter import Sandbox