管理 API 错误码与排障矩阵
本页用于说明管理面 /cubeapi/v1/* 常见错误码在 Cube Sandbox 中通常意味着什么，以及下一步该看哪里。
如果你需要的是 E2B 兼容接口，请优先看：
适用范围
本页主要覆盖：
- Dashboard 同源管理接口
- 运维脚本调用的管理 API
- 管理 API 的鉴权、资源状态和控制类错误
常见错误码矩阵
| 状态码 | 常见含义 | 高频场景 | 下一步 |
|---|---|---|---|
401 | 未携带凭证、凭证无效、鉴权回调返回非 200 | Dashboard 能开但按钮失败；脚本未带 key | 看 API 鉴权说明 和 鉴权与 API Key 排障 |
403 | 外围网关或上游鉴权明确拒绝 | 某些环境启了外部鉴权策略 | 优先看鉴权链路与上游策略 |
404 | 目标资源不存在，或接口路径/资源 ID 错误 | 查询不存在的节点、模板、沙箱 | 先确认资源 ID，再看对应资源页 |
409 | 资源存在，但当前状态不允许执行该操作 | 已运行沙箱重复 resume、不允许 pause | 看资源当前状态与生命周期文档 |
500 | 管理面内部异常，或鉴权回调不可达 | 服务异常、回调链路异常 | 先区分服务本体问题还是鉴权问题 |
逐类说明
401 Unauthorized
最常见于：
- 没带
Authorization或X-API-Key - key 已失效
- 浏览器本地缓存了错误 key
- 鉴权回调返回非 200
建议联动：
403 Forbidden
这类错误更像是上游策略明确拒绝，而不是单纯“没认证”。如果出现，先确认是不是外部鉴权服务或反向代理策略在拒绝。
404 Not Found
优先判断：
- 资源 ID 是否写错
- 资源是否已被删除
- 请求路径是否正确
建议联动：
409 Conflict
通常表示资源状态冲突，而不是资源不存在。
常见于生命周期操作：
- 已经
running的资源继续resume - 当前状态不允许执行
pause
建议联动：
500 Internal Server Error
优先区分：
- 管理面服务本身异常
- 鉴权回调链路异常
建议先看：
推荐排障顺序（管理 API）
- 先看状态码属于哪一类
- 再判断是鉴权、资源不存在、状态冲突还是服务异常
- 再跳到对应资源文档或 runbook