Skip to content

Errors & rate limits

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" }

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 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.

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.