Límites y buenas prácticas
Peticiones por minuto
| Límite | Valor |
|---|---|
| Por clave de API | 600 peticiones por minuto (ventana fija) |
| Respuesta al superarlo | 429 API_KEY_RATE_LIMITED |
Cuando recibas un 429, espera y reintenta con espera creciente (1 s, 2 s, 4 s…) y un pequeño azar. Las cabeceras X-RateLimit-* llegarán en la próxima versión; hasta entonces, mide tú el ritmo.
Tamaños
| Operación | Máximo |
|---|---|
POST /contacts/bulk |
500 ids por llamada, 20 etiquetas |
POST /campaigns/{id}/recipients por ids |
20.000 ids por llamada |
| Etiquetas por contacto | 50, de hasta 60 caracteres |
| Nota de contacto | 4.000 caracteres |
Tamaño de página (pageSize) |
100 (por defecto 20) |
Idempotencia
Crear dos veces el mismo contacto no duplica: la segunda llamada responde 409 CONTACT_PHONE_EXISTS con el contactId del existente. Enviar dos veces una campaña responde 400 («ya fue enviada»). Añadir dos veces la misma audiencia no duplica destinatarios (alreadyIn lo cuenta). Para el resto de operaciones, guarda el id que te devolvemos y no repitas la creación si la respuesta se perdió; la cabecera Idempotency-Key llegará con la próxima versión.
Tiempos
Responde a tus webhooks en menos de 10 segundos (basta un 200 inmediato y procesar después). Las peticiones a la API suelen tardar menos de 300 ms; pon un tiempo máximo de 30 s en tu cliente.
Fechas y zonas horarias
Todas las fechas van en ISO 8601 con zona (2026-10-14T10:21:00.000Z). Al programar una campaña, manda la zona en la fecha (2026-10-20T09:00:00+02:00).
Estabilidad
- La API está versionada en la ruta (
/api/v1). Añadimos campos sin avisar; nunca quitamos ni renombramos campos dentro de la misma versión. - Los cambios se publican en el changelog; las deprecaciones se anuncian con 6 meses.
- Trata los valores de enumeraciones (
status,source,channelType) como listas abiertas: pueden aparecer valores nuevos.