API 错误码与排查
本地 API 由客户端提供，需 专业版会员 且客户端保持运行。端口与 api-key 以 API 菜单为准。
统一响应格式
成功
json
{
"success": true,
"data": {}
}部分接口含 message 字段。
失败
json
{
"success": false,
"error": "错误描述字符串"
}业务失败时 HTTP 常为 200，请始终检查 success。
HTTP 状态码
| 状态码 | 含义 | 典型场景 |
|---|---|---|
200 | 已处理 | 成功，或 body 内 success: false |
400 | 参数错误 | 缺少 id、JSON 无效、Invalid id format |
401 | 未授权 | api-key 错误或缺失；云同步未登录 |
403 | 禁止 | 非会员调用云同步等 |
404 | 不存在 | 环境/分组 id 不存在 |
429 | 限流 | 并发写队列满 |
500 | 服务器错误 | 客户端异常，error 常为 error.message |
认证与权限
error / 响应 | HTTP | 处理 |
|---|---|---|
Unauthorized: Invalid API key | 401 | 从 API 页复制最新 api-key |
| （无响应 / ECONNREFUSED） | — | 启动客户端，核对 localhost:{port} |
请先登录后再进行云同步 | 401 | 客户端登录账号 |
仅限会员使用云同步功能 | 403 | 开通 专业版 |
TIP
2.1.5+ 需在请求头携带 api-key，见 API 概述。
参数校验（400）
error | 说明 |
|---|---|
Missing required parameter: id | POST body 缺少 id |
Missing required parameter: id, name, or remark. | launchBrowser 需三者之一 |
Missing required parameter: cookies | 更新 Cookie 时缺少 cookies |
Missing or invalid parameter: accounts (must be an array) | 平台账号接口需数组 |
Invalid id format | id 非合法整数 |
资源不存在（404）
error 模式 | 说明 |
|---|---|
browser(id: N) not found | 环境 id 不存在 |
Browser with id N not found | 同上（部分接口文案） |
group(id: N) not found | 分组不存在 |
Browser data directory not found for id: N | 环境数据目录已删 |
Browser list is empty or not found. | 环境列表为空 |
启动 / 关闭浏览器
error | 说明 | 建议 |
|---|---|---|
browser(id: N) is running | 已启动（响应可能含 data.debuggingPort） | 直接连 CDP 或先 stopBrowser |
No browser found with id: N / name: … | 搜索条件无匹配 | getBrowserList 核对 |
Multiple browsers found with … | name/remark 不唯一 | 改用唯一 id |
No browser data found for worker ID: N | 本地数据损坏或缺失 | 恢复备份或重建环境 |
Failed to parse proxy from API response | 代理 API 返回格式不对 | 检查提取链接返回 |
Failed to fetch proxy from API: … | 代理 API 请求失败 | 网络/鉴权 |
Browser process closed before DevTools port was detected. | 进程过早退出 | 内核/代理/杀毒软件 |
Failed to detect DevTools port for worker N… | 调试端口未就绪 | 关闭占用同配置的 Chromium |
Browser not found | 通用未找到（文档示例） | 核对 id |
并发与限流
error | HTTP | 说明 |
|---|---|---|
Too many concurrent write requests, please retry later | 429 | 批量写操作过快，稍后重试 |
其它接口
| 场景 | error / 说明 |
|---|---|
| 更新环境 | Browser not found（见各接口页） |
| 插件 / CRX | 下载失败：…（500） |
| Cookie | 404 browser(id: N) not found |
版本差异
error 字符串以当前客户端为准；升级后若文案变化，以实际响应与 Apifox 为准。
调用检查清单
- 专业版有效，客户端已登录
Content-Type: application/json（POST）- 请求头
api-key正确 port与 API 菜单一致- 解析 JSON → 检查
success - Playwright 使用
launchBrowser的debuggingPort，见 Playwright 接入