响应与错误

统一响应格式

接口使用 { code, msg, data } 作为统一响应信封。msg 由后端返回，成功时可能是 ok 也可能是 成功，不要用它判断结果。

成功

{ "code": 0, "msg": "ok", "data": {} }

业务失败

{ "code": 1, "msg": "windowId is required" }

鉴权失败 · HTTP 401

{ "code": 401, "msg": "Authorization Bearer API key is invalid", "data": null }

两套 code

转发类与本机业务接口返回数字 code；/automation/* 失败时返回字符串 code（如 SESSION_NOT_FOUND），并配合非 200 的 HTTP 状态码。解析时请按类型分别处理。

分页信封

/account/list、/proxy/* 列表与 /browser/list 的 data 是统一的分页结构，记录在 data.data：

{
  "code": 0,
  "msg": "成功",
  "data": {
    "count": 10,
    "size": 20,
    "page": 1,
    "total": 1,
    "data": []
  }
}

其中 count 是匹配到的总条数，size 是每页数量（回显请求值），page 是当前页码（回显请求值），total 是总页数，data 是当前页记录。

状态与错误码

本机层只在鉴权失败、路由缺失和自动化错误时使用非 200 状态码，其余情况一律 200 + 业务 code。

场景	HTTP	code	说明
成功	200	0	业务数据在 data 中
本机业务失败	200	1	参数校验或批量操作全部失败，响应可能不含 data 字段
密钥无效或缺失	401	401	Authorization Bearer API key is invalid
路由不存在	404	—	返回纯文本 Not Found，不是 JSON
后端命令未注册	200	-1000	接口不存在或未注册，目前 POST /proxy/detect 固定命中
自动化参数错误	400	INVALID_ARGUMENT	字段缺失或类型不符
动作不在白名单	400	ACTION_NOT_ALLOWED	动作名非法，或 evaluate / runCode 策略未开启
窗口状态不满足	400	WINDOW_NOT_FOUND · WINDOW_NOT_RUNNING	窗口不存在，或未运行且未传 startIfNeeded
客户端标识缺失或越权	403	UNAUTHORIZED	X-Nex-Client-Id 缺失、格式非法，或会话账号与团队上下文已变化
会话或标签页不存在	404	SESSION_NOT_FOUND · PAGE_NOT_FOUND	ID 无效，或会话已被释放
动作超时	408	ACTION_TIMEOUT	超过动作或会话超时上限