Descripción general
La caBRAPI aplica límites de solicitud (rate limit) para garantizar estabilidad, seguridad y rendimiento de la plataforma para todos los clientes.- Los límites se aplican por plan contratado y se miden en ventana fija de 1 minuto.
- Cada ruta tiene un contador independiente — el consumo de un endpoint no afecta el límite de los demás.
- El consumo se cuenta por credencial de API (tu
apiKey) — cada integración mide su propio uso.
Límites por plan
Básico
Hasta 60 solicitudes por minuto.
Profesional
Hasta 120 solicitudes por minuto.
Hyper
Hasta 1.600 solicitudes por minuto.
Si se supera el límite, las nuevas solicitudes se bloquean temporalmente, devolviendo el error
429 hasta que la ventana se reinicie.Headers de control
Toda respuesta que pasa la validación de autenticación y plan incluye headers que permiten acompañar el consumo en tiempo real (las respuestas anticipadas401, 403 o 404 se interrumpen antes de aplicar los headers de rate limit):
Cuando se alcanza el límite, la respuesta de error también incluye:
Cuando se excede el límite
Al superar el límite, la API responde429 Too Many Requests y rechaza nuevas solicitudes hasta que la ventana se reinicie:
La respuesta usa el mismo campo
code que los demás errores de la API. Consulta Errores.Mejores prácticas
- Monitorea el header
X-RateLimit-Remainingpara autorregularse antes de alcanzar el límite. - Al recibir un
429, respeta elRetry-Aftery vuelve a intentarlo solo después del tiempo indicado. - Implementa reintento con backoff exponencial para manejar picos de tráfico.
- Evita el polling agresivo: consulta datos a intervalos mayores o usa webhooks para recibir eventos en tiempo real.
Paginación
En los endpoints de listado, usa los parámetrospage y limit para controlar el volumen de datos por respuesta.
page: entero mayor o igual a1limit: entero entre1y100
400 INVALID_PAGINATION— cuando se combinanpageycursor400 INVALID_PAGINATION_LIMIT400 INVALID_PAGINATION_PAGE400 INVALID_PAGINATION_CURSOR— cuandocursores inválido o malformado
Paginación por cursor
En listas grandes (más de ~100 elementos), prefiere la paginación por cursor, que mantiene el rendimiento en cualquier volumen de datos:- Realiza la primera llamada sin
cursory usa el camponextCursorde la respuesta. - Envía el
nextCursorcomocursoren la siguiente solicitud para avanzar en la lista. - El fin de la lista se indica con
nextCursor: null+hasMore: false(la API responde200con array vacío). - En el modo offset, las respuestas también incluyen
nextCursor/hasMore, permitiendo migrar a cursor sin empezar de cero.