Errors and rate limits
Errors come back as JSON with a readable message and a stable code to branch on.
JSON
{ "error": "This API key doesn't control this output", "code": "forbidden" }Error codes
| Status | Code | What happened |
|---|---|---|
| 400 | invalid_request | The body or path doesn't match the schema. The message says which field is wrong. |
| 401 | unauthorized | No API key, or the key is wrong or revoked. |
| 403 | forbidden | The key doesn't control this output. |
| 404 | not_found | No such output or instance, or it isn't in your workspace. |
| 409 | default_instance | A component's default instance can't be removed. |
| 422 | command_failed | A command in a batch couldn't run, so none did. See below. |
| 429 | rate_limited | Too many commands. Wait the number of seconds in Retry-After. |
Failed commands
A batch runs all or nothing. If any command can't run, nothing changes on air, and the response says which command failed by its position in the batch, counting from 0:
JSON
{ "error": "No component lower-thrid", "code": "command_failed", "index": 1 }Common reasons: an id that isn't in the version the output plays, an instance that belongs to another component, sending both data and instance on in, or an output with no composition yet.
Rate limits
API keys can send 200 command batches every 10 seconds each. Past that, Run commands answers 429 with a Retry-After header. Put many changes in one batch rather than sending them one by one: a batch of up to 100 commands counts once.