Saltar al contenido principal

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 anticipadas 401, 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 responde 429 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.
El tiempo de espera se informa en el header Retry-After (en segundos), no en el cuerpo de la respuesta.

Mejores prácticas

  • Monitorea el header X-RateLimit-Remaining para autorregularse antes de alcanzar el límite.
  • Al recibir un 429, respeta el Retry-After y 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.
Si tu flujo demanda más solicitudes, evalúa el upgrade de plan — el upgrade eleva el límite de inmediato.

Paginación

En los endpoints de listado, usa los parámetros page y limit para controlar el volumen de datos por respuesta.
  • page: entero mayor o igual a 1
  • limit: entero entre 1 y 100
Cuando estos parámetros sean inválidos, la API devuelve:
  • 400 INVALID_PAGINATION — cuando se combinan page y cursor
  • 400 INVALID_PAGINATION_LIMIT
  • 400 INVALID_PAGINATION_PAGE
  • 400 INVALID_PAGINATION_CURSOR — cuando cursor es 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 cursor y usa el campo nextCursor de la respuesta.
  • Envía el nextCursor como cursor en la siguiente solicitud para avanzar en la lista.
  • El fin de la lista se indica con nextCursor: null + hasMore: false (la API responde 200 con array vacío).
  • En el modo offset, las respuestas también incluyen nextCursor/hasMore, permitiendo migrar a cursor sin empezar de cero.
Los límites pueden ajustarse según nuevos planes o condiciones específicas de caBRAPI. Siempre consulta la documentación actualizada para garantizar información correcta.