A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá.
Quando usar
-
Você integra sistemas externos com a API do Cloud Chat e precisa planejar o volume de chamadas sem ser bloqueado.
-
Você recebeu um erro
429(Too Many Requests) e quer entender o motivo. -
Você está importando contatos em massa, disparando conversas proativas de WhatsApp, gerando relatórios ou extrações de dados via API e precisa saber o ritmo seguro de chamadas.
Sobre este artigo
Algumas rotas da API do Cloud Chat têm um limite de requisições por minuto (rate limit). Esse limite existe pra proteger a estabilidade da plataforma em operações mais pesadas, como importação em massa de contatos, geração de relatórios e disparo de mensagens proativas.
A maior parte das rotas da API não tem limite específico configurado — os limites abaixo se aplicam apenas às rotas listadas na tabela.
Se você ainda não tem sua chave de API em mãos, veja Como encontrar sua API Key no Cloud Chat.
Limites por rota
A tabela abaixo mostra o limite de requisições por minuto de cada rota:
| Rota | Limite / minuto |
|---|---|
contacts/external_import |
500 |
conversations/create_proactive_whatsapp_conversation |
200 |
contacts/bulk_create |
100 |
contacts/search e contacts/search/count |
40 |
v2/reports |
20 |
v2/data_extracts |
20 |
integrations/hooks/{id}/process_event (eventos do Copilot) |
20 |
conversations/{id}/transcript |
10 |
messages/{id}/transcription |
10 |
O limite de integrations/hooks/{id}/process_event vale apenas para os eventos do Copilot (reformular, corrigir ortografia, resumir tom, expandir, entre outros). Eventos legados de sugestão de resposta, resumo ou label não passam por esse limite.
Como o limite é aplicado
-
Janela fixa de 1 minuto. O contador reinicia a cada minuto corrido — não é uma janela deslizante.
-
Chave de contagem. Na maioria das rotas, o limite é contado por chave de API (
api_access_token). Em rotas que também podem ser chamadas pelo painel do Cloud Chat (create_proactive_whatsapp_conversation,process_event,contacts/search/contacts/search/countemessages/{id}/transcription), o limite conta tanto pela chave de API quanto pela sessão logada no painel — ou seja, cada agente ou token tem seu próprio contador. -
Não é por IP. O limite não depende do endereço de IP de origem, apenas da chave de API (ou da sessão) usada na chamada.
O que acontece ao exceder o limite
Ao ultrapassar o limite de uma rota, a API responde com o status 429 e o corpo:
{
"error": "Rate limit exceeded. Retry later.",
"retry_after": 42
}
A resposta também inclui estes headers:
| Header | Descrição |
|---|---|
X-RateLimit-Limit |
Limite configurado pra essa rota. |
X-RateLimit-Remaining |
Sempre 0 numa resposta 429. |
X-RateLimit-Reset |
Timestamp (epoch) de quando a janela reinicia. |
Retry-After |
Segundos até poder tentar novamente. |
Sempre respeite o Retry-After antes de tentar de novo. Fazer uma nova tentativa imediata numa rota já limitada só prolonga o bloqueio e não adianta a entrega.
Observações
-
A maioria das rotas da API não tem rate limit específico — os limites acima cobrem só as rotas listadas nesta tabela.
-
Se você precisa de um limite maior pra alguma dessas rotas em um caso de uso legítimo (por exemplo, uma migração pontual de grande volume de contatos), fale com o time de suporte da Cloud Humans antes de rodar a operação.
-
Pra importação em massa de contatos, veja também Como importar contatos em massa via API.
-
Pra uma visão geral de autenticação e operação de dados via API, veja o Guia Mestre — Como acessar e operar dados do Cloud Chat via API.