API 错误码与排查
本地 API 由客户端提供,需 专业版会员 且客户端保持运行。端口与 api-key 以 API 菜单为准。
接口定义:ApiFox。本页错误排查补充自当前客户端;不同版本的错误文字可能不同。
常见响应格式
成功
{
"success": true,
"data": {}
}data 可能是对象、数组或布尔值,也可能不存在。部分接口只返回 success,或包含顶层 message、total、majors、crxPath。不要强制要求所有成功响应都有 data。
运行状态的响应例外
ApiFox 将 isBrowserRunning 定义为原始布尔值;当前客户端返回 success/data 包装。兼容读取方法见 查询环境是否运行。MCP 使用自身的协议报文,不套用本页响应结构。
失败
{
"success": false,
"error": "错误描述字符串"
}不要只检查 HTTP 200。对象响应还需检查 success;运行状态接口需兼容上文的布尔值形态。HTTP 非 2xx 时,即使响应体无法解析为 JSON,也应按失败处理。
HTTP 状态码
| 状态码 | 含义 | 典型场景 |
|---|---|---|
200 | 已处理 | 成功,或 body 内 success: false |
400 | 参数错误 | 缺少 id、JSON 无效、Invalid id format |
401 | 未授权 | api-key 错误或缺失;云同步未登录 |
403 | 禁止 | 非会员调用云同步等 |
404 | 不存在 | 环境/分组 id 不存在 |
409 | 状态冲突 | 未发现显示器或待排列窗口未就绪 |
429 | 限流 | 并发写队列满 |
500 | 服务器错误 | 客户端异常,error 常为 error.message |
501 | 不支持 | 非 Windows 平台调用窗口排列 |
认证与权限
error / 响应 | HTTP | 处理 |
|---|---|---|
Unauthorized: Invalid API key | 401 | 从 API 页复制最新 api-key |
VIP capability lease is missing or expired | 403 | 确认专业版有效、客户端在线且登录状态正常;保留客户端日志排查,勿循环重试 |
| (无响应 / 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 | 当前客户端可作为成功响应的 message,并含 data.debuggingPort | 按 success 和端口判断,不要仅按文字判断失败 |
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 |
Worker authentication failed for worker N: … | 内核授权通道未成功完成 | 保留完整错误、内核版本及客户端日志;先查运行状态,避免重复启动 |
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 |
窗口排列的错误码、部分跳过语义与 Windows 限制见 排列已启动窗口。Cookie 接口需先关闭环境,且 getCookie.data 直接是数组;随机指纹接口只接收 id,不能用于提交自定义字段。
版本差异
error 字符串以当前客户端为准;升级后若文案变化,以实际响应与 Apifox 为准。
调用检查清单
- 专业版有效,客户端已登录
Content-Type: application/json(POST)- 请求头
api-key正确 port与 API 菜单一致- 同时检查 HTTP 状态和响应体;布尔值接口按兼容规则读取
- Playwright 使用
launchBrowser返回的data.debuggingPort,见 Playwright 接入
相关文档
其他当前客户端状态
- 缓存目录迁移期间启动可能返回 409;等待迁移结束再重试。
- 环境写入队列满返回 429;使用有限并发和退避,不要无限重试。
- 内核版本无匹配时返回 400,并可能附带本地内核路径;分享错误响应前先脱敏。
- 读取账号、Cookie、完整环境或访问日志前,请按安全边界与访问日志移除敏感信息。
各接口成功响应与处理器状态
下表按当前客户端源码整理各处理器的显式分支;所有业务请求还可能先经过统一鉴权并返回 401 或 403。JSON 解析失败或超过大小限制可能在处理器之前返回 400 或 413,响应不一定是 JSON。间接异常不保证都在表中。
| 方法与接口 | 成功响应字段 | 处理器其他显式状态 |
|---|---|---|
POST /api/clearCache | success, message | 400, 500 |
GET /api/getBrowserList | success, data[], total | 500 |
POST /api/getBrowserList | success, data[], total | 500 |
GET /api/getBrowserRunningList | success, data[]: id/name/debuggingPort/webdriverPath | 500 |
GET /api/isBrowserRunning | success, data:boolean | 400, 404 |
GET /api/getBrowserFullParameters | success, data: array/object/possibly absent | 500 |
GET /api/getCoreVersions | success, data[], total, majors | 500 |
GET /api/getAvailableCoreVersions | success, data[], total, majors | 500 |
POST /api/addBrowser | success, data.id | 400, 429, 500 |
POST /api/updateBrowser | success | 400, 401, 403, 404, 429, 500 |
GET /api/getCookie | success, data[] / possibly absent | 400, 404, 500 |
POST /api/updateCookie | success | 400, 404, 500 |
POST /api/deleteBrowser | success | 400, 429, 500 |
POST /api/deleteBrowserData | success, message | 400, 500 |
GET /api/getGroupList | success, data[] | 500 |
POST /api/addGroup | success | 500 |
POST /api/updateGroup | success | 404, 500 |
POST /api/deleteGroup | success | 404, 500 |
POST /api/randomizeFingerprint | success, data.id, data.message | 400, 404, 429, 500 |
POST /api/launchBrowser | success, data.debuggingPort, data.webdriverPath? / message? | 400, 401, 403, 404, 409, 500 |
POST /api/arrangeWindows | success, data.arrangedCount/arrangedIds/skipped/monitor | 400, 403, 409, 500, 501 |
POST /api/stopBrowser | success, message? | 400, 404, 500 |
GET /api/getCrxList | success, data[] | 500 |
POST /api/addCrx | success | 500 |
POST /api/deleteCrx | success, crxPath | 500 |
GET /api/getAccountList | success, data[] | 400, 404, 500 |
POST /api/addAccount | success | 400, 500 |
POST /api/deleteAccount | success | 400, 500 |
POST /api/updateAccountList | success | 400, 500 |
MCP 的 POST、GET、DELETE 使用独立 JSON-RPC/Streamable HTTP 响应,不套用此表。



