跳转到内容

API 错误码与排查 ​

本地 API 由客户端提供,需 专业版会员 且客户端保持运行。端口与 api-key 以 API 菜单为准。

接口定义:ApiFox。本页错误排查补充自当前客户端;不同版本的错误文字可能不同。

常见响应格式 ​

成功 ​

json
{
  "success": true,
  "data": {}
}

data 可能是对象、数组或布尔值,也可能不存在。部分接口只返回 success,或包含顶层 message、total、majors、crxPath。不要强制要求所有成功响应都有 data。

运行状态的响应例外

ApiFox 将 isBrowserRunning 定义为原始布尔值;当前客户端返回 success/data 包装。兼容读取方法见 查询环境是否运行。MCP 使用自身的协议报文,不套用本页响应结构。

失败 ​

json
{
  "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 key401从 API 页复制最新 api-key
VIP capability lease is missing or expired403确认专业版有效、客户端在线且登录状态正常;保留客户端日志排查,勿循环重试
(无响应 / ECONNREFUSED)—启动客户端,核对 localhost:{port}
请先登录后再进行云同步401客户端登录账号
仅限会员使用云同步功能403开通 专业版

TIP

2.1.5+ 需在请求头携带 api-key,见 API 概述。

参数校验(400) ​

error说明
Missing required parameter: idPOST 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 formatid 非合法整数

资源不存在(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

并发与限流 ​

errorHTTP说明
Too many concurrent write requests, please retry later429批量写操作过快,稍后重试

其它接口 ​

场景error / 说明
更新环境Browser not found(见各接口页)
插件 / CRX下载失败:…(500)
Cookie404 browser(id: N) not found

窗口排列的错误码、部分跳过语义与 Windows 限制见 排列已启动窗口。Cookie 接口需先关闭环境,且 getCookie.data 直接是数组;随机指纹接口只接收 id,不能用于提交自定义字段。

版本差异

error 字符串以当前客户端为准;升级后若文案变化,以实际响应与 Apifox 为准。

调用检查清单 ​

  1. 专业版有效,客户端已登录
  2. Content-Type: application/json(POST)
  3. 请求头 api-key 正确
  4. port 与 API 菜单一致
  5. 同时检查 HTTP 状态和响应体;布尔值接口按兼容规则读取
  6. Playwright 使用 launchBrowser 返回的 data.debuggingPort,见 Playwright 接入

相关文档 ​

其他当前客户端状态 ​

  • 缓存目录迁移期间启动可能返回 409;等待迁移结束再重试。
  • 环境写入队列满返回 429;使用有限并发和退避,不要无限重试。
  • 内核版本无匹配时返回 400,并可能附带本地内核路径;分享错误响应前先脱敏。
  • 读取账号、Cookie、完整环境或访问日志前,请按安全边界与访问日志移除敏感信息。

各接口成功响应与处理器状态 ​

下表按当前客户端源码整理各处理器的显式分支;所有业务请求还可能先经过统一鉴权并返回 401 或 403。JSON 解析失败或超过大小限制可能在处理器之前返回 400 或 413,响应不一定是 JSON。间接异常不保证都在表中。

方法与接口成功响应字段处理器其他显式状态
POST /api/clearCachesuccess, message400, 500
GET /api/getBrowserListsuccess, data[], total500
POST /api/getBrowserListsuccess, data[], total500
GET /api/getBrowserRunningListsuccess, data[]: id/name/debuggingPort/webdriverPath500
GET /api/isBrowserRunningsuccess, data:boolean400, 404
GET /api/getBrowserFullParameterssuccess, data: array/object/possibly absent500
GET /api/getCoreVersionssuccess, data[], total, majors500
GET /api/getAvailableCoreVersionssuccess, data[], total, majors500
POST /api/addBrowsersuccess, data.id400, 429, 500
POST /api/updateBrowsersuccess400, 401, 403, 404, 429, 500
GET /api/getCookiesuccess, data[] / possibly absent400, 404, 500
POST /api/updateCookiesuccess400, 404, 500
POST /api/deleteBrowsersuccess400, 429, 500
POST /api/deleteBrowserDatasuccess, message400, 500
GET /api/getGroupListsuccess, data[]500
POST /api/addGroupsuccess500
POST /api/updateGroupsuccess404, 500
POST /api/deleteGroupsuccess404, 500
POST /api/randomizeFingerprintsuccess, data.id, data.message400, 404, 429, 500
POST /api/launchBrowsersuccess, data.debuggingPort, data.webdriverPath? / message?400, 401, 403, 404, 409, 500
POST /api/arrangeWindowssuccess, data.arrangedCount/arrangedIds/skipped/monitor400, 403, 409, 500, 501
POST /api/stopBrowsersuccess, message?400, 404, 500
GET /api/getCrxListsuccess, data[]500
POST /api/addCrxsuccess500
POST /api/deleteCrxsuccess, crxPath500
GET /api/getAccountListsuccess, data[]400, 404, 500
POST /api/addAccountsuccess400, 500
POST /api/deleteAccountsuccess400, 500
POST /api/updateAccountListsuccess400, 500

MCP 的 POST、GET、DELETE 使用独立 JSON-RPC/Streamable HTTP 响应,不套用此表。