# Responses and errors

> The response envelope and every response code returned by the RooQi bridge.

- Source: https://rooqi.cn/docs/developers/errors/
- Platforms: Mac only (macOS 14 or later)
- Version: Bridge protocol v1
- Status: Preview — not yet publicly released
- Last verified: 2026-10-26 against RooQiIPCShared/Wire.swift and Client.swift

## Response envelope

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

`resultJSON` is a JSON-encoded string with the method’s result; parse it a second time. Envelopes never contain local paths or underlying system errors.

## Codes

| Code | Meaning | What to do |
|---|---|---|
| `ready` | Success | — |
| `approvalRequired` | The user hasn’t approved yet; RooQi is showing a window | Wait, then call the same request again |
| `denied` | The user declined | Start a new connection to ask again |
| `appUnavailable` | RooQi isn’t running | Open RooQi |
| `transportUnavailable` | The connection service isn’t reachable | Enable External Connections; allow the background service |
| `duplicateApp` | More than one RooQi instance is registered | Quit extra copies of RooQi |
| `shuttingDown` | RooQi is closing the connection | Retry later on a new connection |
| `protocolMismatch` | Bridge and app versions don’t match | Use the bridge inside the same RooQi.app |
| `unsupportedMethod` | Unknown tool or method | Check the reference |
| `malformedRequest` | Missing, extra or invalid fields | Fix the input |
| `busy` | Too many calls in flight, or another approval is pending | Wait for earlier calls |
| `timeout` | No reply within 8 seconds; the connection is retired | Reconnect (needs new approval) |
| `resultTooLarge` | The result exceeds 16,384 bytes | Read less (e.g. a smaller PDF region) |
| `readUnavailable` | The content can’t be read right now | Check that the document still exists and is saved |
| `mutationRejected` | The write was refused before it was submitted (e.g. version mismatch) | Re-read, then retry with a new operation |
| `mutationUncertain` | The write may have been committed | Query or retry with the **same** `operationID`; never a new one |

## Retry rules

- **Idempotency:** writes are keyed by `operationID`. Reusing the same ID with the same content is safe; changing the content under the same ID is rejected.
- **Connections:** `timeout`, `transportUnavailable`, `protocolMismatch` and `malformedRequest` responses end the connection and all its grants.