Skip to Content
CallMitraDocs

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 4xx error.
  • 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-Id uses 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:

HeaderMeaning
RateLimit-LimitRequests allowed in the current window (for example 300).
RateLimit-RemainingRequests left in the current window.
RateLimit-ResetSeconds until the window resets.
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-ResetThe same values under the older names, for clients that expect them.
Retry-AfterOn 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

  1. Stop sending requests with that key.
  2. Wait for Retry-After seconds.
  3. 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 (limit up to 200 on most lists) rather than many small ones.
  • Watch RateLimit-Remaining and 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 answers 429 campaign_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 answers 409 (for example campaign_call_limit_reached or carrier_capacity_reached). Your plan's limit on simultaneous calls answers 429 concurrent_call_limit_reached. See Calling refusals.

  • WhatsApp sends: up to 50 messages per second per workspace. Above that, POST /whatsapp/messages answers 429 rate_limit_exceeded with Retry-After: 1.

  • Placing calls with POST /calls: a fixed number of calls per workspace per UTC day (2,000 by default). Above it, createCall answers 429 daily_call_limit_reached, with Retry-After counting down to 00:00 UTC.

  • Webhook test events and redeliveries: 10 per endpoint per minute, shared between sendTestWebhook and redeliverWebhook. Above it you get 429 rate_limit_exceeded with Retry-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.

On this page