Rate limits

Request limits per IP and per API key, the rate limit headers, and the call concurrency and CPS limits.

Tried limits how fast you can send requests and how many calls you can run at once. Every limit returns 429 Too Many Requests with a message that says which limit you hit and when to retry.

Request limits#

Limit	Default	Applies to
Per IP address	3000 requests per minute	Every route except `/health` and `/internal/*`, counted before authentication.
Per API key	600 requests per minute	Every request made with a secret API key.
Per public key, per IP	30 requests per minute	Browser requests made with a public key.
Per public key	The key's `rate_limit_per_minute`, when set	All browser requests made with that public key.

Each limit is a sliding one-minute window. With Redis configured, the counts are shared across all API instances. Without Redis, or while Redis is unreachable, each instance keeps its own window.

Change the per-key limit#

Set rate_limit_per_minute (1 to 100000) on a key with Create API key or Update API key. It replaces the 600 default for that key, higher or lower. Set it to null to return to the default. Split traffic across keys when separate services should not share a budget.

Headers#

Requests made with an API key return these headers:

Header	Description
`x-ratelimit-limit`	The key's limit per minute.
`x-ratelimit-remaining`	Requests left in the current window.
`x-ratelimit-reset`	Seconds until the oldest request in the window expires and frees a slot.

A 429 from the per-IP or per-key limit also sets retry-after (seconds), with the same value as x-ratelimit-reset.

429 responses#

{
  "status": 429,
  "message": "Rate limit exceeded for this API key: 600 requests per minute. Retry in 12s."
}

Message	Limit
`Rate limit exceeded for this IP address: <n> requests per minute. Retry in <s>s.`	Per IP.
`Rate limit exceeded for this API key: <n> requests per minute. Retry in <s>s.`	Per API key.
`Too many requests from this address. Retry in <s>s.`	Public key, per IP.
`This public key is over its limit of <n> requests per minute.`	Public key.
`Concurrency limit reached (<current>/<limit>). Try again later or raise the limit.` (with `, burst <n>` after the limit when burst is on)	Call concurrency.
`CPS limit for <number> reached (<cps>/s). Retry in <ms> ms.`	Calls per second.
`This call already has 5 viewers. Try again when someone leaves.`	Live call monitoring allows 5 viewers per call.

Retry#

Wait for retry-after (or the time in the message), then retry. For bulk work, read x-ratelimit-remaining and slow down before it reaches zero. Retry concurrency and CPS errors with exponential backoff.

Call concurrency#

Concurrency is the number of calls the workspace runs at the same moment. New workspaces start with a limit of 20. A call counts while it is ongoing (up to 3 hours from creation) or registered (up to 10 minutes).

Outbound and web calls are refused when the active count reaches the limit minus any reserved inbound slots.
Inbound calls can use the reserved slots.
Burst, when on, lets calls continue past the limit up to the lower of 3 times the limit and the limit plus 300.
Batch calls can reserve part of the limit with reserved_concurrency so other traffic keeps headroom.

Read the current state with Get concurrency. Change reserved inbound slots and burst with Update concurrency settings.

Calls per second#

Each number has a calls-per-second (CPS) budget for outbound dialling:

Number type	Default CPS
Telnyx or Twilio numbers	4
Custom SIP trunk numbers	10

Set cps_limit (0.1 to 150) on a number to change it. When the budget is used, the call waits up to 5 seconds for a slot. If none frees up, the request returns 429.

The dashboard's sign-in routes have their own per-minute limits: 10 sign-ups per IP, 30 sign-ins per IP and 10 per email, 10 password reset requests per IP and 3 per email. These do not apply to API keys.

Spend limits#

Running out of credit or reaching the monthly budget returns 402, not 429. See Errors.