问题排查

API Key 不可用

确认设置了 DEVBOX_API_KEY，凭证仍有效，且属于当前服务允许的使用范围。401 通常表示缺少或无效凭证，403 表示没有对应权限。不要通过关闭 TLS 校验解决鉴权问题。

沙箱不存在

检查是否使用创建响应中的真实沙箱 ID。默认模式下到期即不可继续使用；删除后的沙箱不能通过 connect() 恢复。暂停中的沙箱可以在保留期内恢复。

暂停或恢复很慢

暂停需要保存状态，耗时与内存、磁盘和运行负载有关。自动暂停还存在调度延迟。先通过 get_info() / getInfo() 查询状态；不要因调用超时就认定操作未执行。

恢复后的文件仍可访问，但旧的网络流不保证继续有效。进程使用 PID 重连，目录监听重新建立。

创建失败或配额不足

查询并删除不再需要的运行或暂停沙箱。配额可能在账户内共享，只查看当前沙箱列表不一定能看到全部占用。没有可清理资源却持续受限时，提供请求 ID 给服务支持人员。

创建返回网络错误或超时，不代表服务端一定没有创建成功。先查询沙箱列表，再决定是否重新创建，避免重复占用资源。

命令没有输出

确认命令是否确实向 stdout / stderr 写入内容，程序是否缓冲输出，是否还在等待 stdin 结束。后台命令通过 wait() 获取结果；disconnect() 不会停止远端进程。

重连只接收新的输出，不能读取断开期间的输出历史。需要可靠保存时将结果写入文件。

Git 返回 127 或无法访问 GitHub

退出码 127 通常表示命令不存在，检查模板是否安装 Git。DNS、网络连通性和目标仓库权限由沙箱运行环境决定；本地机器能访问 GitHub 不代表沙箱也能访问。

HTTPS 或连接失败

核对服务域名、DNS、代理和证书信任链。服务端证书必须匹配实际访问域名。跳过证书校验会使凭证和数据存在被截获的风险，不应作为正常使用方式。

遇到 429 时降低请求频率，并检查是否为资源配额限制。对命令执行、文件写入等操作，不应在结果不明时直接重复提交。

提交问题

提供 SDK 版本、Python 或 Node.js 版本、发生时间、方法名、错误码及请求 ID；命令问题附退出码与脱敏输出。不要附 API Key、Token、私钥或敏感文件内容。