当前云沙箱以兼容 E2B SDK / CLI 为主，暂不维护独立的云沙箱 OpenAPI 错误码页面。开发者排查问题时，应先结合 E2B SDK 抛出的异常、HTTP 状态码、CLI 输出和云沙箱兼容边界判断问题类型。
本文先提供常见错误归类和排查顺序。正式错误码、错误结构和可重试策略以后续产品文档为准。
鉴权与 Endpoint
常见现象：
SDK 或 CLI 返回未认证、无权限、请求失败。
SDK 可用但 CLI 不可用。
同一 API Key 在一个环境可用，换到另一个环境失败。
优先排查：
E2B_API_KEY是否按创建 API Key创建。CLI 版本是否支持
E2B_API_KEY认证。E2B_API_URL和E2B_DOMAIN是否都指向云沙箱端点。API Key、Endpoint、模板和 Sandbox 是否属于同一账号和同一地域。
是否把过期、删除或权限不足的 API Key 用在当前环境。
模板与 Sandbox 创建
常见现象：
创建 Sandbox 失败。
指定模板不存在或不可用。
创建耗时过长、超时或返回配额相关错误。
优先排查：
模板名称或模板 ID 是否正确。
模板构建状态是否为可用状态。
当前账号、地域和模板是否一致。
当前账号是否达到 Sandbox 并发、模板构建或资源规格配额。
创建参数中的超时时间、环境变量、元数据大小是否符合 SDK 和产品约束。
连接、暂停与终止
常见现象：
Sandbox.connect()失败。暂停后无法恢复。
kill()后继续访问失败。
优先排查：
sandboxId是否属于当前账号和地域。Sandbox 是否已经被主动终止、超时回收或因异常退出。
连接时使用的 API Key 和 Endpoint 是否与创建时一致。
业务代码是否在任务完成后提前调用了
kill()。
终止后的 Sandbox 不能继续连接或恢复。需要保留现场时，应使用暂停与恢复能力，并在业务状态中记录对应 sandboxId。
命令执行
常见现象：
命令返回非零退出码。
长任务无输出、卡住或被超时终止。
交互式命令表现与本地终端不同。
优先排查：
命令是否依赖当前工作目录、环境变量、网络或本地文件。
是否需要 PTY。只有交互式 CLI、彩色输出、进度条或依赖 TTY 判断的命令才建议开启 PTY。
是否设置了过短的命令超时或 Sandbox 超时。
stdout / stderr 是否被业务代码正确读取和记录。
用户输入是否经过校验，避免 shell 注入或意外删除文件。
文件读写
常见现象：
文件不存在、权限不足或路径无效。
写入成功但后续命令读不到文件。
上传、下载大文件失败。
优先排查：
是否使用 Sandbox 内的绝对路径。
文件是否写入了与命令执行相同的 Sandbox。
目录是否已创建，路径是否存在大小写差异。
文件大小、数量和路径深度是否超过产品或 SDK 限制。
是否把 Sandbox 本地文件系统误当成跨 Sandbox 的持久化存储。
Code Interpreter
常见现象：
runCode()/run_code()执行失败。多次执行之间变量状态不符合预期。
图表、富媒体或文件输出不可用。
优先排查：
是否使用支持 Code Interpreter 的模板。
依赖包是否已安装在模板或当前 Sandbox 中。
是否在同一 Context 内执行需要共享状态的代码。
输出类型是否属于当前兼容范围。
代码是否访问了不存在的文件、受限网络或超出资源配额。
受限或暂不兼容能力
如果错误来自以下能力，不应优先按参数问题处理：
Metrics、Logs、Network Config Update：当前属于受限能力，不适合作为生产依赖。
文件自定义元数据：云沙箱当前不支持。SDK 可能抛出
TemplateException: File metadata requires envd 0.6.2 or later.；这不是 Python 参数错误，普通文件读写不受影响。Snapshots、Volume、Team 管理、API Key / Access Token 管理：当前不属于云沙箱 E2B 兼容主路径。
E2B 托管 MCP Gateway、自定义域名、代理隧道、Bring Your Own Cloud：当前不应直接照搬到云沙箱接入方案。
遇到这类问题时，应先回到E2B SDK 兼容 API 清单确认能力边界，再判断是否需要替代方案。