The most up-to-date documentation for the Cloud Humans APIs is at docs.cloudhumans.com/api-reference. If this article and the reference differ, the reference prevails.
When to use
-
You integrate external systems with the Cloud Chat API and need to plan your call volume without being blocked.
-
You received a
429(Too Many Requests) error and want to understand why. -
You are importing contacts in bulk, sending proactive WhatsApp conversations, generating reports or data extracts via API, and need to know the safe pace of calls.
About this article
Some Cloud Chat API routes have a requests-per-minute limit (rate limit). This limit exists to protect the platform's stability during heavier operations, such as bulk contact imports, report generation and sending proactive messages.
Most API routes have no specific limit configured — the limits below apply only to the routes listed in the table.
If you don't have your API key at hand yet, see How to find your API Key in Cloud Chat.
Limits per route
The table below shows the requests-per-minute limit for each route:
| Route | Limit / minute |
|---|---|
contacts/external_import |
500 |
conversations/create_proactive_whatsapp_conversation |
200 |
contacts/bulk_create |
100 |
contacts/search and contacts/search/count |
40 |
v2/reports |
20 |
v2/data_extracts |
20 |
integrations/hooks/{id}/process_event (Copilot events) |
20 |
conversations/{id}/transcript |
10 |
messages/{id}/transcription |
10 |
The limit for integrations/hooks/{id}/process_event applies only to Copilot events (rephrase, fix spelling, summarize tone, expand, among others). Legacy reply suggestion, summary or label events are not subject to this limit.
How the limit is applied
-
Fixed 1-minute window. The counter resets every calendar minute — it is not a sliding window.
-
Counting key. On most routes, the limit is counted per API key (
api_access_token). On routes that can also be called from the Cloud Chat dashboard (create_proactive_whatsapp_conversation,process_event,contacts/search/contacts/search/countandmessages/{id}/transcription), the limit is counted both by API key and by the logged-in dashboard session — that is, each agent or token has its own counter. -
Not per IP. The limit does not depend on the source IP address, only on the API key (or session) used in the call.
What happens when you exceed the limit
When you exceed a route's limit, the API responds with status 429 and the body:
{
"error": "Rate limit exceeded. Retry later.",
"retry_after": 42
}
The response also includes these headers:
| Header | Description |
|---|---|
X-RateLimit-Limit |
Limit configured for this route. |
X-RateLimit-Remaining |
Always 0 in a 429 response. |
X-RateLimit-Reset |
Timestamp (epoch) of when the window resets. |
Retry-After |
Seconds until you can try again. |
Always respect Retry-After before trying again. Retrying immediately on a route that is already limited only prolongs the block and does not speed up delivery.
Notes
-
Most API routes have no specific rate limit — the limits above cover only the routes listed in this table.
-
If you need a higher limit for one of these routes for a legitimate use case (for example, a one-off migration of a large volume of contacts), talk to the Cloud Humans support team before running the operation.
-
For bulk contact imports, also see How to import contacts in bulk via API.
-
For an overview of authentication and data operations via API, see the Master Guide — How to access and operate Cloud Chat data via API.