La documentación más actualizada de las APIs de Cloud Humans está en docs.cloudhumans.com/api-reference. Si hay diferencias entre este artículo y la referencia, prevalece lo que está allí.
Cuándo usar
-
Integras sistemas externos con la API de Cloud Chat y necesitas planificar el volumen de llamadas sin ser bloqueado.
-
Recibiste un error
429(Too Many Requests) y quieres entender el motivo. -
Estás importando contactos de forma masiva, enviando conversaciones proactivas de WhatsApp, generando informes o extracciones de datos vía API y necesitas saber el ritmo seguro de llamadas.
Sobre este artículo
Algunas rutas de la API de Cloud Chat tienen un límite de solicitudes por minuto (rate limit). Este límite existe para proteger la estabilidad de la plataforma en operaciones más pesadas, como la importación masiva de contactos, la generación de informes y el envío de mensajes proactivos.
La mayoría de las rutas de la API no tiene un límite específico configurado: los límites a continuación se aplican solo a las rutas listadas en la tabla.
Si todavía no tienes tu clave de API a mano, consulta Cómo encontrar tu API Key en Cloud Chat.
Límites por ruta
La siguiente tabla muestra el límite de solicitudes por minuto de cada ruta:
| Ruta | Límite / minuto |
|---|---|
contacts/external_import |
500 |
conversations/create_proactive_whatsapp_conversation |
200 |
contacts/bulk_create |
100 |
contacts/search y contacts/search/count |
40 |
v2/reports |
20 |
v2/data_extracts |
20 |
integrations/hooks/{id}/process_event (eventos del Copilot) |
20 |
conversations/{id}/transcript |
10 |
messages/{id}/transcription |
10 |
El límite de integrations/hooks/{id}/process_event se aplica solo a los eventos del Copilot (reformular, corregir ortografía, resumir tono, expandir, entre otros). Los eventos heredados de sugerencia de respuesta, resumen o etiqueta no están sujetos a este límite.
Cómo se aplica el límite
-
Ventana fija de 1 minuto. El contador se reinicia cada minuto calendario; no es una ventana deslizante.
-
Clave de conteo. En la mayoría de las rutas, el límite se cuenta por clave de API (
api_access_token). En las rutas que también pueden llamarse desde el panel de Cloud Chat (create_proactive_whatsapp_conversation,process_event,contacts/search/contacts/search/countymessages/{id}/transcription), el límite se cuenta tanto por la clave de API como por la sesión iniciada en el panel; es decir, cada agente o token tiene su propio contador. -
No es por IP. El límite no depende de la dirección IP de origen, solo de la clave de API (o de la sesión) usada en la llamada.
Qué pasa al superar el límite
Al superar el límite de una ruta, la API responde con el status 429 y el cuerpo:
{
"error": "Rate limit exceeded. Retry later.",
"retry_after": 42
}
La respuesta también incluye estos headers:
| Header | Descripción |
|---|---|
X-RateLimit-Limit |
Límite configurado para esta ruta. |
X-RateLimit-Remaining |
Siempre 0 en una respuesta 429. |
X-RateLimit-Reset |
Timestamp (epoch) de cuándo se reinicia la ventana. |
Retry-After |
Segundos hasta que puedas intentarlo de nuevo. |
Respeta siempre el Retry-After antes de volver a intentarlo. Hacer un nuevo intento inmediato en una ruta ya limitada solo prolonga el bloqueo y no acelera la entrega.
Observaciones
-
La mayoría de las rutas de la API no tiene un rate limit específico: los límites anteriores cubren solo las rutas listadas en esta tabla.
-
Si necesitas un límite mayor para alguna de estas rutas en un caso de uso legítimo (por ejemplo, una migración puntual de un gran volumen de contactos), habla con el equipo de soporte de Cloud Humans antes de ejecutar la operación.
-
Para la importación masiva de contactos, consulta también Cómo importar contactos de forma masiva vía API.
-
Para una visión general de la autenticación y la operación de datos vía API, consulta la Guía Maestra — Cómo acceder y operar datos de Cloud Chat vía API.