Cuotas y límites de frecuencia

Una factura por organización

El uso de la plataforma se mide por organización, no por clave — todas las claves de tu organización consumen un único presupuesto mensual compartido y comparten los límites de frecuencia. Una clave, una factura: AI, maps y design consumen el mismo medidor de la organización.

El presupuesto se restablece según un ciclo de calendario mensual.

Qué incluye tu plan

El plan de tu organización determina tanto a qué puede acceder una clave como el presupuesto mensual compartido de tokens:

Plan	API surface	Monthly API tokens	Monthly map loads
Free	solo Basemaps — una publishable key con scope maps y producto tile	n/a (sin scope ai)	50,000
Pro	plataforma completa (ai, maps, design; browser + server keys)	5,000,000	50,000
Enterprise	plataforma completa	50,000,000	50,000

Todos los planes incluyen la misma asignación de map-loads — los planes se diferencian por tokens, superficie API y funciones. Los volúmenes Enterprise por encima de la asignación se conceden como ampliaciones por organización, no mediante un nivel de plan superior.

Las claves del plan Free sirven embeds de basemap, medidos como map loads en lugar de tokens. Para acceder a las superficies AI y design, mejora el plan en kaleidr.com/billing. Los cambios de plan se aplican a tus claves existentes en unos minutos; no hace falta hacer re-mint — aunque una clave creada en Free vuelve a recibir scopes cuando se rota la próxima vez.

El body de 429

Una solicitud que superaría el límite devuelve 429 Too Many Requests con un body plano en el nivel superior — los payloads 429 estructurados no envuelven los campos en un objeto detail (solo los 429 con string-detail, como map_load_hard_stop, lo hacen):

{
  "error": "b2b.tokens_exceeded",
  "meter": "b2b.tokens",
  "tier": "pro",
  "limit": 5000000,
  "used": 5000000,
  "remaining": 0,
  "reset_at": "2026-10-01T00:00:00Z",
  "reset_in_seconds": 123456
}

En endpoints de streaming, el límite también aparece durante el stream mediante un quota SSE event, para que tu UI pueda reaccionar antes de que termine el stream.

Consulta Errors — Envelope para la distinción completa entre 429 planos y envueltos.

Superar la asignación

Lo que ocurre por encima de la asignación depende del plan, y ambos casos son deliberadamente diferentes.

Free se detiene al llegar a la asignación. Una solicitud que la superaría devuelve 429 map_load_quota_exceeded. Ese límite define el producto de basemap gratuito.

Pro y Enterprise continúan sirviendo. Un exceso en una cuenta de pago es una conversación de billing, no una caída del servicio, por lo que tus embeds no se apagan a mitad de mes — registramos el exceso y hacemos seguimiento.

Esa flexibilidad no es ilimitada. Los planes de pago se detienen al llegar a cinco veces la asignación con 429 map_load_hard_stop. Ningún embed normal alcanza ese punto; el límite existe para que alguien que copie una publishable key del código fuente de tu página no pueda generar una factura ilimitada a tu nombre. Los paquetes adicionales de map-load elevan la asignación, y el techo escala con ella.

Si alcanzas la banda flexible regularmente, necesitas más asignación en lugar de un workaround — contáctanos.

Acceso al basemap

Los designed basemaps forman parte de tu cuenta Kaleidr, no son una tile API pública independiente: los embeds <kaleidr-map> y el SDK se autorizan mediante tu publishable key (scope maps), y cada map load — la apertura de un shared-map, una vista publicada/incrustada o una sesión de basemap del SDK, aproximadamente 20 tile requests — consume la asignación mensual compartida descrita arriba. El uso directo de terceros de tile.kaleidr.com fuera de un keyed embed se bloquea con 429 y este body:

{
  "error": "tile_access_restricted",
  "message": "Direct access to tile.kaleidr.com requires a Kaleidr account. Kaleidr-hosted maps and embeds are unaffected — see the docs.",
  "docs": "https://docs.kaleidr.com/platform-api/quota-and-rate-limits"
}

El 429 también incluye un header Retry-After: 3600 — no reintentes antes.

Si necesitas más que la asignación, contáctanos — se conceden volúmenes superiores por organización y Enterprise puede servir desde un CDN independiente.

Límites de frecuencia y concurrencia

Hay dos límites delante de la cuota, y ambos descartan el exceso con un 429 en lugar de ponerlo en cola:

• Solicitudes por minuto, por clave — ventana móvil de 60 segundos. Cada clave tiene su propia frecuencia.
• Streams concurrentes, por organización — solicitudes de streaming simultáneas entre todas las claves de tu organización.

Reintenta con backoff. Un 429 aquí significa "demasiado rápido ahora mismo"; un 429 que incluya meter en el body significa que has alcanzado el límite mensual.

Cómo gestionarlo

• Trata 429 como "reduce el ritmo / mejora el plan", no como "roto". Haz backoff y reintenta.
• Muestra el evento quota durante el stream en tu UI (presupuesto restante).
• Consulta Errors para ver la tabla completa de estados.