Errors & rate limits
Error format
Section titled “Error format”Failed requests return a non-2xx status and a JSON body with an error message:
{ "error": "studio not found" }Authentication failures also include a machine-readable code:
{ "error": "invalid API key", "code": "KEY_EXPIRED" }Plan limits
Section titled “Plan limits”Some actions are capped by your organization’s plan (for example the number of studios or
channels per SIP trunk). Hitting a cap returns 409 with a stable shape you can detect.
limit names the cap (for example studios, numbers, ai_screening, trunk_channels):
{ "error": "plan_limit", "limit": "studios", "message": "This plan allows only 1 studio — upgrade to Premium to add more."}Status codes
Section titled “Status codes”| Status | Meaning |
|---|---|
200 / 201 |
Success (201 when something was created). |
204 |
Success with no response body (typically deletes). |
400 |
The request was invalid. The message says which field. |
401 |
Missing, invalid, expired or revoked API key. |
403 |
The key isn’t allowed to do this: a read-only key making a change, or a studio-app-only feature. |
404 |
The resource doesn’t exist or belongs to another organization. |
409 |
Conflict, such as a plan limit or a resource in the wrong state. |
429 |
Rate limited. Wait for the number of seconds in Retry-After. |
5xx |
Something went wrong on our side. Safe to retry with backoff. |
Rate limits
Section titled “Rate limits”Each API key can make 600 requests per minute. Past that, requests return 429
with a Retry-After header (in seconds) until the window resets:
{ "error": "rate limited", "code": "RATE_LIMITED" }If you need a higher limit, contact support.