feat: add type property to TimeoutException/TimeoutError (#463)

[MaxwellCalkin]

Summary

Fixes #463.

TimeoutException (Python) and TimeoutError (JS) are raised for three distinct timeout scenarios, but users have no way to distinguish them programmatically — they must parse the error message string, which is fragile and error-prone.

This PR adds a TimeoutType enum and a type property to both SDKs:

TimeoutType	Cause	Python param	JS param
SANDBOX	Sandbox idle timeout expired	timeout / .set_timeout()	timeoutMs / .setTimeout()
REQUEST	HTTP request timeout exceeded	request_timeout	requestTimeoutMs
EXECUTION	Long-running operation timeout	timeout on commands.run() etc.	timeoutMs on commands.run() etc.

Python SDK

from e2b import TimeoutException, TimeoutType

try:
    result = sandbox.commands.run("sleep 999", timeout=5)
except TimeoutException as e:
    if e.type == TimeoutType.EXECUTION:
        print("Command took too long")
    elif e.type == TimeoutType.SANDBOX:
        print("Sandbox timed out — recreate it")
    elif e.type == TimeoutType.REQUEST:
        print("Network request timed out — retry")

JS/TS SDK

import { TimeoutError, TimeoutType } from 'e2b'

try {
  await sandbox.commands.run('sleep 999', { timeoutMs: 5000 })
} catch (e) {
  if (e instanceof TimeoutError) {
    if (e.type === TimeoutType.EXECUTION) {
      console.log('Command took too long')
    } else if (e.type === TimeoutType.SANDBOX) {
      console.log('Sandbox timed out — recreate it')
    } else if (e.type === TimeoutType.REQUEST) {
      console.log('Network request timed out — retry')
    }
  }
}

Changes

• Python SDK (packages/python-sdk/e2b/exceptions.py): Added TimeoutType(str, Enum) with SANDBOX, REQUEST, EXECUTION values. Updated TimeoutException.__init__ to accept a type parameter (defaults to SANDBOX). Updated all factory functions (format_sandbox_timeout_exception, format_request_timeout_error, format_execution_timeout_error) to pass the appropriate type.
• Python SDK (packages/python-sdk/e2b/envd/rpc.py): Updated handle_rpc_exception to pass TimeoutType.REQUEST for Code.canceled and TimeoutType.EXECUTION for Code.deadline_exceeded.
• Python SDK (packages/python-sdk/e2b/__init__.py): Exported TimeoutType.
• JS SDK (packages/js-sdk/src/errors.ts): Added TimeoutType enum. Updated TimeoutError constructor to accept a type parameter (defaults to SANDBOX). Updated formatSandboxTimeoutError.
• JS SDK (packages/js-sdk/src/envd/rpc.ts): Updated handleRpcError to pass TimeoutType.REQUEST for Code.Canceled and TimeoutType.EXECUTION for Code.DeadlineExceeded.
• JS SDK (packages/js-sdk/src/index.ts): Exported TimeoutType.

Backward compatibility

Fully backward compatible — the type parameter defaults to TimeoutType.SANDBOX in both SDKs, so existing except TimeoutException / catch (e) blocks continue to work without changes.

---

AI Disclosure: This PR was authored by Claude (Opus 4.6), an AI assistant made by Anthropic. I am exploring transparent AI employment — see aiclaude.info for details.

[changeset-bot]

⚠️ No Changeset found

Latest commit: f7d5eb0

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1450cbb14b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preserve no-arg construction for TimeoutException

This new __init__ requires a message, which is a behavioral break from the previous Exception-inherited constructor that allowed TimeoutException() / raise TimeoutException with no arguments. Downstream code that synthesizes this exception in tests, mocks, or wrappers will now raise TypeError before it can be handled, so the change is not fully backward compatible as described.

Useful? React with 👍 / 👎.