Rate limits
Each API key can make 300 requests per minute. Read the RateLimit headers and back off on 429.
Each API key has its own budget of 300 requests per minute. The budget is a fixed 60-second window: when it runs out, requests answer 429 until the window resets.
Keys do not share a budget with each other or with your team's console sessions (the console has its own budget of 120 requests per minute per workspace), so a busy integration cannot slow down people working in the console, and one integration cannot starve another.
Which requests count
- Every authenticated request made with the key counts once, including requests that end in a
4xxerror. - A request refused before the key is accepted (no key, unknown, expired, or an endpoint no key may call) does not count against any budget.
- An agency key acting in client workspaces with
X-Workspace-Iduses one budget across all of them (Agencies). - Lead intake webhooks authenticated with an integration key (not an API key) have their own limits and do not use this budget.
Need a higher limit for a production integration? Contact support with your expected volume.
Response headers
Every response to an API-key request, successful or not, carries the current state of the key's budget:
| Header | Meaning |
|---|---|
RateLimit-Limit | Requests allowed in the current window (for example 300). |
RateLimit-Remaining | Requests left in the current window. |
RateLimit-Reset | Seconds until the window resets. |
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset | The same values under the older names, for clients that expect them. |
Retry-After | On 429 only: seconds to wait before retrying. |
HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 300
RateLimit-Remaining: 0
RateLimit-Reset: 17
Retry-After: 17
Content-Type: application/json
{
"detail": "Too many requests",
"error": {
"type": "rate_limit_error",
"code": "rate_limit_exceeded",
"message": "Too many requests. Slow down and retry later.",
"param": null,
"docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded",
"requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69"
}
}Handling 429
- Stop sending requests with that key.
- Wait for
Retry-Afterseconds. - Retry with exponential backoff and jitter if it happens again.
async function callWithRetry(url, init, attempts = 5) {
for (let attempt = 0; attempt < attempts; attempt++) {
const res = await fetch(url, init);
if (res.status !== 429 && res.status < 500) return res;
const retryAfter = Number(res.headers.get('Retry-After'));
const backoff = Math.min(30, 2 ** attempt) + Math.random();
await new Promise((r) => setTimeout(r, (retryAfter || backoff) * 1000));
}
throw new Error('CallMitra API still failing after retries');
}Only retry POST requests that are safe to repeat; see Idempotency.
Stay under the limit
- Use bulk endpoints for big jobs: create a campaign with its leads in one request, or act on many leads at once.
- Use webhooks for call results instead of polling.
- Ask for larger pages (
limitup to 200 on most lists) rather than many small ones. - Watch
RateLimit-Remainingand slow down before it reaches zero.
Other limits
Calling has its own limits, separate from the request budget:
-
A campaign's daily call limit (
maxCallsPerDay, default 50 per campaign per day in the campaign's timezone). When auto-dial reaches it, the campaign waits for the next day. Asking for a manual call on that campaign once it is reached answers429campaign_daily_cap_reached. Waiting a few seconds will not help; the limit resets at local midnight. -
Concurrent calls: per campaign (
maxConcurrentCalls), per phone number, and per carrier account. A call that would exceed one answers409(for examplecampaign_call_limit_reachedorcarrier_capacity_reached). Your plan's limit on simultaneous calls answers429concurrent_call_limit_reached. See Calling refusals. -
WhatsApp sends: up to 50 messages per second per workspace. Above that,
POST /whatsapp/messagesanswers429rate_limit_exceededwithRetry-After: 1. -
Placing calls with
POST /calls: a fixed number of calls per workspace per UTC day (2,000 by default). Above it,createCallanswers429daily_call_limit_reached, withRetry-Aftercounting down to 00:00 UTC. -
Webhook test events and redeliveries: 10 per endpoint per minute, shared between sendTestWebhook and redeliverWebhook. Above it you get
429rate_limit_exceededwithRetry-After.
Check error.code to tell a request-budget 429 (rate_limit_exceeded) from a calling 429. The codes each endpoint can return are listed in the API reference.