Developer
Log in

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_limited has data.retry_after_ms: when to try again.
  • rejected has 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.

CodeNameMeaning
-32700parse_errorThe message isn't JSON.
-32600invalid_requestNot a JSON-RPC 2.0 request, or too many requests at once.
-32601method_not_foundNo such method.
-32602invalid_paramsA parameter is missing, unknown, of the wrong type or out of range. The message names it.
-32603internalSomething went wrong inside Studio.
-32001unauthorizedNot authorized: no pairing yet, or a wrong pairing code.
-32010unknown_actionNo action with that id.
-32011not_foundThe scene, layer, source, effect, automation, collection or destination named doesn't exist.
-32012confirm_requiredA destructive action without its confirmation.
-32013rate_limitedToo many of these too fast. data.retry_after_ms says when to try again.
-32014failedStudio tried and it didn't work. The message says why.
-32015unavailableNot possible right now: no collection open, the GPU still starting, or a feature this computer doesn't have.
-32016rejectedThe scene model refused the change. data has its reason and the index of the refused command.
-32017unknown_topicNo such state topic.
-32018forbiddenThis 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.stop and chat.clear without "confirm": true, and chat.moderate takes no defaults at all. Guard destructive controls on your side too, for example with a long press.
  • Updates never start mid-stream. update.install is 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 (after retry_after_ms) and unavailable (when the thing it waited for is ready). Retrying invalid_params or not_found won'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.

to open · ↑ ↓ to move · Esc to close