Developers
Responses and errors
The response envelope and every response code returned by the RooQi bridge.
Response envelope
{
"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,protocolMismatchandmalformedRequestresponses end the connection and all its grants.