错误码参考

所有 SDK 错误都继承自 SandboxError，携带 code（错误码）、message（消息）、suggestion（建议）、docs_url（文档 URL）属性。

from agent_sandbox.models.errors import SandboxError

try:
    sandbox = await Sandbox.create(template="nonexistent")
except SandboxError as e:
    print(f"[{e.code}] {e.message}")
    print(f"建议: {e.suggestion}")

E1xxx — 认证错误（AuthenticationError）

排查步骤

1. 运行 abx config get sandbox_api_key 确认认证状态
2. 检查环境变量是否正确设置
3. 确认 API Key 未过期或被吊销
4. 对于 E1002，检查系统时钟是否准确（date 命令）

E2xxx — 创建错误（SandboxCreationError）

排查步骤

1. 确认模板名称正确（abx template list）
2. 对于 E2002，检查 abx list 是否有大量闲置沙箱
3. 对于 E2004，检查 template.yaml 的 YAML 语法和字段值
4. 对于 E2005–E2008（生成路径），按输出中的 Quick Setup 操作；不想使用 模板生成时可显式传 abx create --template <名称>。其中 E2008 需把缺失项（或示例描述）补进参数，或传 -y 跳过澄清直接生成

E3xxx — 执行错误（ExecutionError）

E3004 详细说明

说明（ADR 2026-09-23）：大多数模块的运行时 check_capability() 门控已移除。CommandsModule、FilesModule、NetworkModule 不再在调用时抛出 E3004。例外：CodeContextModule 保留了 code 能力门控——其所有方法（run、create_context、list_contexts、restart_context、remove_context）在 code 能力缺失时仍会抛出 CapabilityNotSupportedError（E3004，fail-closed）。E3004 也仍在模板解析/模型校验时抛出（如 resolve_capabilities()）。

CapabilityNotSupportedError 携带 capability 属性，指示缺少的能力名。

try:
    result = await sandbox.run_code("print(1)")
except CapabilityNotSupportedError as e:
    print(f"缺少能力: {e.capability}")  # "code"

标准能力：shell、files、code、terminal、ports

默认能力集：{shell, files, code}（不声明 capabilities 时自动获得）

E4xxx — 文件系统错误（FileOperationError）

注意：FileNotFoundError_ 类名带下划线后缀，以避免遮蔽 Python 内置 FileNotFoundError。

E5xxx — 网络错误（NetworkError）

注意：ConnectionError_ 类名带下划线后缀，以避免遮蔽 Python 内置 ConnectionError。

注意：GitHubRateLimitError 与 NetworkError 共享 E5000 错误码——对调用方仍是普通网络错误，CLI 通过该子类识别限流并提供一次性交互式 github_token 引导。

E6xxx — 会话错误（SessionError）

E7xxx — 部署与构建错误

部署错误（DeployError）

模板构建错误

Docker/ACR 错误

异常层级结构

classDiagram
    SandboxError <|-- AuthenticationError
    SandboxError <|-- SandboxCreationError
    SandboxError <|-- SandboxNotFoundError
    SandboxError <|-- ExecutionError
    SandboxError <|-- FileOperationError
    SandboxError <|-- NetworkError
    SandboxError <|-- SessionError
    SandboxError <|-- DeployError
    SandboxError <|-- TemplateBuildError
    SandboxError <|-- TemplateBuildTimeoutError
    SandboxError <|-- DockerBuildError
    SandboxError <|-- ACRPushError
    SandboxError <|-- ACRLoginError

    AuthenticationError <|-- InvalidAPIKeyError
    AuthenticationError <|-- TokenExpiredError
    AuthenticationError <|-- InvalidCredentialsError

    SandboxCreationError <|-- TemplateNotFoundError
    SandboxCreationError <|-- QuotaExceededError
    SandboxCreationError <|-- RegionUnavailableError
    SandboxCreationError <|-- TemplateParseError
    SandboxCreationError <|-- QwenCodeNotInstalledError
    SandboxCreationError <|-- QwenCodeCredentialError
    SandboxCreationError <|-- AICodegenError
    SandboxCreationError <|-- DescriptionClarificationError

    ExecutionError <|-- CommandTimeoutError
    ExecutionError <|-- ProcessError
    ExecutionError <|-- CodeExecutionError
    ExecutionError <|-- CapabilityNotSupportedError

    FileOperationError <|-- FileNotFoundError_
    FileOperationError <|-- PermissionDeniedError

    NetworkError <|-- ConnectionError_
    NetworkError <|-- GitHubRateLimitError

    SessionError <|-- SessionNotFoundError
    SessionError <|-- SessionAlreadyExistsError

    DeployError <|-- DeployLLMKeyMissingError
    DeployError <|-- DeployAgentError
    DeployError <|-- DeployTimeoutError

    class SandboxError { E0000 }
    class AuthenticationError { E1000 }
    class InvalidAPIKeyError { E1001 }
    class TokenExpiredError { E1002 }
    class InvalidCredentialsError { E1003 }
    class SandboxCreationError { E2000 }
    class TemplateNotFoundError { E2001 }
    class QuotaExceededError { E2002 }
    class RegionUnavailableError { E2003 }
    class TemplateParseError { E2004 }
    class QwenCodeNotInstalledError { E2005 }
    class QwenCodeCredentialError { E2006 }
    class AICodegenError { E2007 }
    class DescriptionClarificationError { E2008 }
    class SandboxNotFoundError { E2009 }
    class ExecutionError { E3000 }
    class CommandTimeoutError { E3001 }
    class ProcessError { E3002 }
    class CodeExecutionError { E3003 }
    class CapabilityNotSupportedError { E3004 }
    class FileOperationError { E4000 }
    class FileNotFoundError_ { E4001 }
    class PermissionDeniedError { E4002 }
    class NetworkError { E5000 }
    class ConnectionError_ { E5001 }
    class GitHubRateLimitError { E5000 }
    class SessionError { E6000 }
    class SessionNotFoundError { E6001 }
    class SessionAlreadyExistsError { E6002 }
    class DeployError { E7000 }
    class DeployLLMKeyMissingError { E7001 }
    class DeployAgentError { E7002 }
    class DeployTimeoutError { E7003 }
    class TemplateBuildError { E7010 }
    class TemplateBuildTimeoutError { E7011 }
    class DockerBuildError { E7020 }
    class ACRPushError { E7021 }
    class ACRLoginError { E7022 }

相关 SDK 文档

这些异常类的 Python 导入路径（from agent_sandbox.models.errors import ...）列在 python-sdk 仓库中 SDK 的错误码参考里。