# 响应与错误

> RooQi 桥接返回的响应信封与全部响应代码。

- Source: https://rooqi.cn/zh-hans/docs/developers/errors/
- Platforms: 仅 Mac（macOS 14 或更高版本）
- Version: 桥接协议 v1
- Status: 预览——尚未公开发布
- Last verified: 2026-10-26，依据 RooQiIPCShared/Wire.swift 与 Client.swift

## 响应信封

```json
{
  "version": 1,
  "requestID": "…",
  "code": "ready",
  "instanceID": "…",
  "processID": 1234,
  "brokerInstanceID": "…",
  "resultJSON": "{…}"
}
```

`resultJSON` 是编码为字符串的方法结果，需要再解析一次。信封不会包含本机路径或底层系统错误。

## 代码

| 代码 | 含义 | 处理 |
|---|---|---|
| `ready` | 成功 | — |
| `approvalRequired` | 用户尚未批准，RooQi 正在显示窗口 | 稍候再次调用同一请求 |
| `denied` | 用户拒绝 | 新建连接后再请求 |
| `appUnavailable` | RooQi 未运行 | 打开 RooQi |
| `transportUnavailable` | 连接服务不可达 | 启用外部连接，允许后台服务 |
| `duplicateApp` | 检测到重复的 RooQi 实例登记 | 退出多余的 RooQi 副本 |
| `shuttingDown` | RooQi 正在关闭连接 | 稍后用新连接重试 |
| `protocolMismatch` | 桥接与 App 版本不匹配 | 使用同一 RooQi.app 内的桥接程序 |
| `unsupportedMethod` | 未知工具或方法 | 对照参考文档 |
| `malformedRequest` | 字段缺失、多余或无效 | 修正输入 |
| `busy` | 进行中的调用过多，或另一项批准尚未完成 | 等待之前的调用 |
| `timeout` | 8 秒内无响应，连接已作废 | 重新连接（需要重新批准） |
| `resultTooLarge` | 结果超过 16,384 字节 | 读取更少内容（如更小的 PDF 区域） |
| `readUnavailable` | 暂时无法读取 | 确认文稿仍存在且已保存 |
| `mutationRejected` | 写入在提交前被拒（如版本不符） | 重新读取后，以新操作重试 |
| `mutationUncertain` | 写入可能已提交 | 用**同一** `operationID` 查询或重试，不要换新 ID |

## 重试规则

- **幂等：** 写入以 `operationID` 为键。用同一 ID、同一内容重试是安全的；同一 ID 换成不同内容会被拒绝。
- **连接：** `timeout`、`transportUnavailable`、`protocolMismatch` 与 `malformedRequest` 会结束当前连接及其全部授权。