附录 B：常见问题 - VirtualBrowser

Q：所有接口都返回 403 VIP capability lease is missing or expired？

A：api-key 已通过，但 VIP 能力校验未通过（租约过期或未登录）。请重新登录客户端，或在客户端内确认会员状态。

Q：调用写接口偶发 429？

A：环境列表写操作有并发队列，上限 1000 个待处理请求，超出直接返回 429。请控制并发或加重试退避。

Q：账号保存成功了，但浏览器里没有自动填充？

A：三个排查点：① origin_url 是否带了协议和结尾斜杠（如 https://www.facebook.com/）；② 保存后是否重启过环境（Chrome 启动时才加载 Login Data）；③ 目标平台登录页域名是否与 origin_url 完全一致。

Q：调用时提示文件被占用（500）？

A：涉及环境数据的接口（cookie、账号、缓存、删除数据）都要求环境已关闭。请先调 stopBrowser，等 1~2 秒再重试。

Q：调用 addBrowser 传了 accountList，但账号没保存？

A：先看返回的 accountCount。若为 0，检查每条是否都带 origin_url 和 username_value（缺一个该条会被跳过）；若返回了 accountError，说明写账号库失败（通常是环境数据被占用），可改用 /api/addAccount 补写。

Q：分页参数传了没生效？

A：page 和 pageSize 必须同时传，只传一个会返回全量数据。

Q：服务端口每次都不同，怎么固定？

A：端口由客户端启动时自动选择，不提供固定端口配置。请通过客户端界面或全局配置读取实际端口后再发起请求。