> ## Documentation Index
> Fetch the complete documentation index at: https://developers.cloudtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.
# CloudTalk API Rate Limits, Headers, and Throttling
> CloudTalk enforces a 60 requests-per-minute limit per company. Learn how to read rate-limit headers and implement retry logic to avoid 429 errors.
The CloudTalk REST API (v1.7) enforces a rate limit to ensure fair resource allocation and platform stability for all customers. Every API key in your company shares a single quota, so high-volume background jobs and real-time user-facing calls compete for the same budget. Understanding the limit, reading the headers the API returns, and implementing graceful backoff logic will prevent your integration from hitting `429` errors in production.
## Default Limit
CloudTalk enforces a limit of **60 requests per minute per company** on the core API. This quota is shared across all API keys in your account — if you have multiple services or background workers issuing API calls, their requests all count toward the same 60 req/min ceiling.
**The Dialer partner API has its own budget.** Requests to `https://api.cloudtalk.io/v1/dialer/*` are limited per company in a dedicated 60 req/min budget, so they do not consume the core 60 req/min quota. Dialer `429` responses do carry the same three `X-CloudTalkAPI-*` headers described below, but the body follows the Dialer error shape: `{ "statusCode": 429, "message": "Too Many Requests", "error": "Too Many Requests", "correlationId": "YevPQs" }`.
When you exceed the rate limit, the API immediately returns **HTTP 429 Too Many Requests**. On the core API the body follows the standard error envelope — `{"responseData": {"status": 429, "message": "Too Many Requests"}}`. The request is **not** queued or retried automatically; you must handle the retry yourself, and continued hammering will not make the window reset any sooner.
***
## Rate-Limit Headers
When a request is rate limited, the API returns a `429` along with three headers describing your quota. Read them from the `429` response to decide when to resume:
| Header | Type | Description |
| -------------------------- | ------------------------ | --------------------------------------------------------------------------------- |
| `X-CloudTalkAPI-Limit` | integer | Maximum number of requests allowed in the current one-minute window. |
| `X-CloudTalkAPI-Remaining` | integer | Number of requests you may still make before the window resets. |
| `X-CloudTalkAPI-ResetTime` | integer (Unix timestamp) | The Unix epoch second at which the current window expires and your quota refills. |
### Reading Headers with cURL
Use `-D -` to dump the response headers to stdout, and `-o /dev/null` to discard the body. Avoid `-I`: it issues a `HEAD` request rather than the documented `GET`.
```bash cURL — inspect response headers theme={"system"}
curl -sS -D - -o /dev/null \
-u KEY_ID:KEY_SECRET \
-H "Accept: application/json" \
'https://my.cloudtalk.io/api/calls/index.json?limit=1&page=1'
```
When the request is rate limited, the response looks like this:
```text Sample 429 response headers theme={"system"}
HTTP/2 429
content-type: application/json; charset=utf-8
x-cloudtalkapi-limit: 60
x-cloudtalkapi-remaining: 0
x-cloudtalkapi-resettime: 1712150460
```
Convert `X-CloudTalkAPI-ResetTime` from Unix timestamp to a human-readable time with `date -r 1712150460` (macOS) or `date -d @1712150460` (Linux).
These headers are documented as accompanying a `429`. If your client observes them on successful responses too, you can use them to track consumption proactively — but do not build logic that *requires* them to be present outside a `429`.
***
## Implementing Retry Logic
The recommended strategy for handling `429` responses is **exponential backoff with jitter**. Wait for a short delay after the first failure, double the delay on each subsequent failure, and add a small random jitter to prevent multiple workers from retrying in lockstep.
```python Python — exponential backoff on 429 theme={"system"}
import time
import random
import requests
KEY_ID = "your_key_id"
KEY_SECRET = "your_key_secret"
def api_get(url: str, params: dict = None, max_retries: int = 5) -> dict:
"""
Perform a GET request with exponential backoff on HTTP 429.
Raises after max_retries exhausted.
"""
delay = 1.0 # initial back-off in seconds
for attempt in range(1, max_retries + 1):
response = requests.get(
url,
auth=(KEY_ID, KEY_SECRET),
headers={"Accept": "application/json"},
params=params,
)
if response.status_code == 429:
# Optionally honour the reset time if provided
reset_time = response.headers.get("X-CloudTalkAPI-ResetTime")
if reset_time:
wait = max(0, int(reset_time) - int(time.time())) + 1
else:
wait = delay + random.uniform(0, 1)
print(
f"[Attempt {attempt}/{max_retries}] Rate limited. "
f"Retrying in {wait:.1f}s..."
)
time.sleep(wait)
delay *= 2 # exponential back-off
continue
response.raise_for_status()
return response.json()
raise RuntimeError(f"Exceeded {max_retries} retries due to rate limiting.")
# Example usage
data = api_get(
"https://my.cloudtalk.io/api/calls/index.json",
params={"limit": 100, "page": 1},
)
print(data["responseData"]["itemsCount"], "total calls")
```
Rather than sleeping until an arbitrary back-off interval, parse `X-CloudTalkAPI-ResetTime` from the response headers and sleep until that Unix timestamp. This minimises wasted wait time when the window is about to reset anyway.
***
## Requesting a Higher Limit
If your use case genuinely requires more than 60 requests per minute — for example, a real-time dashboard polling dozens of agents simultaneously — contact [CloudTalk Support](https://www.cloudtalk.io/contact/) and include:
* A description of your integration and why the current limit is insufficient.
* The approximate sustained request rate you need (e.g. "\~200 req/min during business hours").
* Your account identifier or API key prefix.
CloudTalk reviews limit-increase requests on a case-by-case basis and may apply a higher per-company threshold to your account.
***
## Best Practices
Following these practices will help you stay well within the rate limit even as your integration scales.
[Contact actions](/api-reference/bulks/contact-actions) packs up to 10 contact add/edit/delete operations into a single request — one unit of quota instead of ten.
Data like agent lists, phone numbers, and groups changes infrequently. Cache responses locally for a few minutes rather than fetching on every page load.
Apply the filters an endpoint documents — `date_from`, `date_to` and `contact_id` on call history, for instance. Smaller result sets require fewer pages and fewer total requests to export.
***
## Header Quick Reference
| Header | Example Value | How to Use |
| -------------------------- | ------------- | ----------------------------------------------------------------------- |
| `X-CloudTalkAPI-Limit` | `60` | Confirms your account's current rate limit ceiling. |
| `X-CloudTalkAPI-Remaining` | `0` | Requests left in the window. Slow down or pause as this approaches `0`. |
| `X-CloudTalkAPI-ResetTime` | `1712150460` | Sleep until this timestamp to resume at full quota. |
## Related topics
- [CloudTalk REST API v1.7 — Complete Developer Reference](/api-reference/overview.md)
- [How to Paginate CloudTalk API Collection Responses](/guides/pagination.md)
- [Changelog](/changelog.md)