Control API
Errors and limits
Errors are plain English and ready to show, and every code keeps its meaning forever. The limits are few and generous; the safety rules are firm.
What an error looks like
JSON-RPC
← { "jsonrpc": "2.0", "id": 9, "error": { "code": -32012, "message": "stream.stop needs \"confirm\": true" } }The message is written to be shown to people as it is, and says what to do next where it can ("Sign in to Velora in Studio first."). Some errors carry data:
rate_limitedhasdata.retry_after_ms: when to try again.rejectedhas the scene model's reason and the index of the command it refused.
Every code
Generated from the catalog's errors list. Use the name for an enum or an exception type; the SDKs give each code its own class.
| Code | Name | Meaning |
|---|---|---|
-32700 | parse_error | The message isn't JSON. |
-32600 | invalid_request | Not a JSON-RPC 2.0 request, or too many requests at once. |
-32601 | method_not_found | No such method. |
-32602 | invalid_params | A parameter is missing, unknown, of the wrong type or out of range. The message names it. |
-32603 | internal | Something went wrong inside Studio. |
-32001 | unauthorized | Not authorized: no pairing yet, or a wrong pairing code. |
-32010 | unknown_action | No action with that id. |
-32011 | not_found | The scene, layer, source, effect, automation, collection or destination named doesn't exist. |
-32012 | confirm_required | A destructive action without its confirmation. |
-32013 | rate_limited | Too many of these too fast. data.retry_after_ms says when to try again. |
-32014 | failed | Studio tried and it didn't work. The message says why. |
-32015 | unavailable | Not possible right now: no collection open, the GPU still starting, or a feature this computer doesn't have. |
-32016 | rejected | The scene model refused the change. data has its reason and the index of the refused command. |
-32017 | unknown_topic | No such state topic. |
-32018 | forbidden | This paired device isn't allowed to do that. Studio chooses what each device may do in Settings › Remote control; data.scope names what it needs. |
The SDKs' class for each code is in the error reference.
Limits
| Limit | Value |
|---|---|
| Message size | 1 MB per WebSocket text frame |
| Requests in flight | 32 per connection; queue the rest |
| Chat sends | Per connection: three at once, then one every three seconds (-32013 with retry_after_ms) |
meters |
Ten pushes a second while you follow it |
| Pairing code | Works once, for five minutes; five wrong tries cancel it |
Everything else, such as how many topics you follow or how often you call an action, is up to you. Be kind to the streamer's computer: follow meters only while you show it, and don't poll what Studio already pushes.
Safety
- Destructive actions need explicit parameters and have no defaults. Studio refuses
stream.stopandchat.clearwithout"confirm": true, andchat.moderatetakes no defaults at all. Guard destructive controls on your side too, for example with a long press. - Updates never start mid-stream.
update.installis refused while Studio is live, recording or keeping a replay buffer. See Updates. - Secrets never cross the API: no stream keys, platform tokens or WHIP addresses. The only token the API ever sends is a paired device's own, once, when it pairs.
- Network access is off by default. On this computer, the API listens on 127.0.0.1 only. Devices on the network connect over TLS, only after the streamer allows it and pairs them. See Devices on your network.
- API changes are ordinary edits. They show in every panel at once and aren't undo steps, so a remote never buries the streamer's own edits in Edit › Undo.
Handling errors well
- Show the message. It's already written for people.
- Retry only what can succeed later:
rate_limited(afterretry_after_ms) andunavailable(when the thing it waited for is ready). Retryinginvalid_paramsornot_foundwon't help. - Re-read the catalog on
unknown_action. The action may come from a newer Studio than the one you're connected to. - On
not_found, refresh from the topic. The scene or source was probably renamed or deleted; an id from the topic is the fix.

