Límites de tasa

La API de RealityConnect limita la tasa de solicitudes por organización mediante un token bucket por familia de rutas. Esta página cubre los buckets, las cabeceras que lleva toda respuesta limitada por tasa, y qué hacer ante un 429 Too Many Requests.

---

Buckets

Cada bucket tiene una capacidad (número máximo de tokens, es decir, el tamaño de ráfaga) y una tasa de recarga (tokens añadidos por segundo, es decir, el rendimiento sostenido). Cada solicitud consume un token; cuando el bucket está vacío, la solicitud se rechaza con 429.

Bucket	Capacidad	Tasa de recarga	Cubre
assets	1000	10/s	RealityAssets, tipos de activo, categorías de activo, creación/lectura/listado/eliminación de objetos de negocio
twin	1000	10/s	Espacio de RealityTwin, POI, zonas, borradores
platform	1000	10/s	Sitio, nodo de datos, Data Bundle, plugins
plan	1000	10/s	Espacio de RealityPlan, activos de modelo
library	1000	10/s	Modelos y etiquetas de la Asset Library
embed	100	2/s	Emisión de sesiones de embed
users	1000	10/s	Usuarios, grupos, roles, invitaciones
sitefiles	1000	10/s	Archivos de sitio

La limitación de tasa es por organización: todas las aplicaciones OAuth y los usuarios que actúan en nombre de la misma organización comparten un bucket por familia.

Cabeceras de respuesta

Toda respuesta limitada por tasa, correcta o no, lleva estas cabeceras:

Cabecera	Significado
X-RateLimit-Limit	La capacidad del bucket
X-RateLimit-Remaining	Tokens restantes en el bucket
X-RateLimit-Reset	Segundos hasta que el bucket vuelva a estar lleno
X-RateLimit-Policy	{capacity};w={window}, donde window (en segundos) es capacity / refillRate

Solo en 429 Too Many Requests, la respuesta también lleva Retry-After (segundos hasta que haya al menos un token disponible) y este cuerpo:

{
  "statusCode": 429,
  "message": "Too Many Requests",
  "error": "rate_limited"
}

Gestión del 429

Aplica un retroceso usando Retry-After en lugar de una espera fija o un reintento inmediato: reintentar de inmediato contra un bucket vacío solo produce otro 429. Para cargas de trabajo sostenidas de alto volumen, ajusta el ritmo de las solicitudes para mantenerte por debajo de la tasa de recarga del bucket, en lugar de agotar la capacidad de golpe y esperar el reinicio.

¿Qué sigue?

• Consulta la referencia de la API para ver las operaciones exactas de cada bucket.