Límites de tasa

Las solicitudes a la API REST cuentan para un límite de tasa cuando se hacen con cualquiera de estas credenciales:

• Claves de API, incluidas las claves de ejecutables y de chatbots
• Credenciales de partner: claves de partner, certificados y tokens de acceso OAuth de partner
• Tokens de acceso OAuth
• Tokens federados

El límite es por organización: todas estas credenciales que actúan en tu organización comparten un único presupuesto, con los mismos límites, así que crear más credenciales no lo aumenta. Las solicitudes de una credencial de partner cuentan para la organización cliente indicada en x-auth-org, o para la organización partner si falta ese encabezado.

Cómo funcionan los límites

Rhombus usa un algoritmo de token bucket (cubo de tokens). Dos valores rigen tu rendimiento:

• Una tasa de recarga sostenida (solicitudes por segundo): tu límite máximo en estado estable.
• Una capacidad de ráfaga, aproximadamente 10× la tasa de recarga de forma predeterminada: margen que absorbe picos cortos.

Las ráfagas tienen éxito de inmediato mientras el cubo tiene tokens. Una vez que el cubo se vacía, el tráfico sostenido por encima de la tasa de recarga devuelve 429 hasta que el cubo se vuelve a llenar.

Las tasas predeterminadas se aplican a todas las organizaciones, y los mismos límites aplican tanto en la región de EE. UU. como en la de la UE (regiones) — se aplican dentro de la región de tu organización. Para solicitar un límite más alto, contacta al soporte de Rhombus.

Respuestas limitadas

Dos tipos de límite responden con 429 Too Many Requests y un encabezado Retry-After, el número de segundos que debes esperar (al menos 1):

HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json

{"error":true,"errorCode":"RATE_LIMITED","errorMsg":"…","status":429,"txid":"…", …}

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{"error":true,"errorMsg":"Clip creation is temporarily throttled for device(s) [AAAAAAAAAAAAAAAAAAAAAA]; retry after 12 second(s)"}

Para el límite de la organización, Retry-After se calcula a partir de la tasa de recarga de tu organización. Decide según el código de estado o errorCode, y espera los segundos de Retry-After.

Límites por cámara para clips y fotogramas

La creación de clips (spliceV3 y los anteriores splice y spliceV2) y los fotogramas exactos (getExactFrameUri, getExactFrameData y getLiveImage) también tienen un límite por cámara, independiente del límite de tu organización y compartido por todo lo que usa esa cámara, incluida la consola:

• Cada cámara admite una ráfaga de solicitudes y después una tasa sostenida más lenta.
• Un rechazo inicia un periodo de espera, y las solicitudes durante ese periodo también se rechazan. Los rechazos posteriores a ese periodo alargan la siguiente espera, así que reintentar antes de tiempo solo te retrasa.
• Una solicitud que incluye varias cámaras se rechaza completa si cualquiera de ellas supera su límite, y Retry-After es la espera más larga.

Para exportar o muestrear mucho video, reparte las solicitudes entre cámaras y a lo largo del tiempo en lugar de enviarlas seguidas para una sola cámara.

Registro de clientes OAuth

El registro dinámico anónimo de clientes (POST /oauth/register) tiene sus propios límites: 10 registros por hora desde una misma dirección IP de cliente y 100 por hora en total. Por encima de cualquiera de los dos, el registro responde 429 con Retry-After y un cuerpo de error de OAuth, donde error es la cadena temporarily_unavailable. Consulta Iniciar sesión con Rhombus.

Manejo de los límites de tasa

1. Lee el encabezado Retry-After

   El encabezado Retry-After te indica exactamente cuántos segundos debes esperar, calculado a partir de la tasa de recarga de tu organización. Prefiere siempre este valor en lugar de retrasos codificados.

2. Pausa las solicitudes

   Deja de enviar solicitudes durante el tiempo especificado en el encabezado.

3. Reintenta tu solicitud

   Después del periodo de espera, reintenta la solicitud original.

Estrategia de reintento

Espera los segundos de Retry-After ante un 429 y, ante errores temporales del servidor, espera de forma exponencial con jitter completo:

espera = aleatorio(0, min(espera_máxima, espera_base × 2^intento))

Errores: reintentos y espera exponencial tiene un cliente en Python y JavaScript que aplica estas reglas y explica qué respuestas no reintentar.

Cuándo reintentar

Reintenta los 429, las respuestas 5xx y los fallos de red; no reintentes otras respuestas 4xx ni las respuestas 200 con "error": true. Errores explica cada caso.

Throttling de notificaciones de alertas

Las notificaciones de alertas (distintas de los límites de tasa de la API) tienen un intervalo mínimo configurable entre alertas consecutivas del mismo tipo para un dispositivo dado. Esto evita la fatiga por alertas debida a eventos de alta frecuencia como la detección de movimiento.

Configura esto por política y por tipo de actividad. Durante la ventana de retroceso, las alertas duplicadas para el mismo dispositivo y tipo de actividad se suprimen del lado del servidor.