快速起步
状态码与排障速查
网关响应规范、业务状态码与常见报错排障指引
为了保证高吞吐与灵活性，浪花平台采用行业主流的双轨响应模型。调用接口前请先了解以下规范。
1. 响应结构规范 (Dual-Track)
| 接口类型 | 典型路径 | 响应结构 | 成功判断条件 |
|---|---|---|---|
| 技能执行接口 | POST /gateway/skill/execute | {"success": true, "message": "...", "data": {...}} | res.success === true |
| 驱动与管理接口 | POST /auth/*, POST /robot/screen-stream/*, POST /gateway/device-binding/* | {"code": 200, "msg": "...", "data": {...}} | res.code === 200 |
避坑提醒：调用 /gateway/skill/execute 时，网关返回的 HTTP 状态码通常为 200，必须通过 res.success 判断物理动作是否实际完成，切勿仅判断 res.code === 200。
2. 核心状态码与错误信息
| 状态码 / message | 含义说明 | 触发原因与解决方案 |
|---|---|---|
401 Unauthorized | 鉴权失败 | 请求头缺少 X-AppKey 或密钥格式错误。请前往驱动台核对。 |
403 Forbidden | 跨账号越权 | 当前 AppKey 所属用户与目标 device_id 不匹配。确认手机是否已扫码绑定到当前账号。 |
USER_BUSY | 人工接管打断 | 手机端用户主动点击了悬浮窗接管，或手机开启了“请勿打扰”模式。Agent 需立即暂停自动化，捕获此异常并等待用户放行。 |
设备不在线 | 物理设备离线 | 手机处于关机、断网或长连接未就绪状态。请检查手机 Wi-Fi 与网络连接。 |
二维码已过期 | 绑定 Ticket 失效 | 扫码绑定票据默认 TTL 为 180 秒，超时需重新生成票据。 |
| 该手机已有其他会话| WebRTC 推流冲突 | 另一客户端账号正在独占推流中。需等待旧会话断开或使用同账号无缝接管。 |
3. 常见物理动作异常与防护机制
① 滑动坐标自动钳制 (y1 >= 150)
- 现象：当传入
y1 < 150进行向下滑动时，系统自动将起始点下移至150。 - 原因：防止滑动手势误触 Android 系统顶部通知栏与驱动中心。
② 拟真输入延迟机制
- 现象：调用
ui.input时，字符上屏耗时并非瞬间完成。 - 原因：底层内置 60~150ms 的逐字随机微延迟，完全贴合人类真实输入节奏，保障与第三方商业应用的平滑交互，避免触发高频异常拦截。
③ 息屏自动唤醒
- 现象：手机处于黑屏状态时直接调用
app.launch依然能成功运行。 - 原因：系统会在启动目标 App 前自动检测屏幕背光，并在毫秒级内完成自动唤醒与解锁屏幕。