Quotas et limites de débit

Une facture par organisation

L’utilisation de la plateforme est mesurée par organisation, et non par clé — toutes les clés de votre organisation consomment le même budget mensuel partagé et partagent les rate limits. Une clé, une facture : AI, maps et design débitent tous le même compteur d’organisation.

Le budget est réinitialisé selon un cycle calendaire mensuel.

Ce que votre forfait comprend

Le forfait de votre organisation définit à la fois ce qu’une clé peut atteindre et le budget mensuel partagé de tokens :

Plan	API surface	Monthly API tokens	Monthly map loads
Free	Basemaps uniquement — une publishable key avec le scope maps et le produit tile	n/a (pas de scope ai)	50,000
Pro	plateforme complète (ai, maps, design; browser + server keys)	5,000,000	50,000
Enterprise	plateforme complète	50,000,000	50,000

Chaque forfait possède la même allocation de map-loads — les forfaits se différencient par les tokens, la surface API et les fonctionnalités. Les volumes Enterprise supérieurs à l’allocation sont accordés comme augmentations par organisation, pas comme un échelon de forfait supérieur.

Les clés du forfait Free servent les embeds de basemap, mesurés en map loads plutôt qu’en tokens. Pour accéder aux surfaces AI et design, mettez à niveau sur kaleidr.com/billing. Les changements de forfait s’appliquent à vos clés existantes en quelques minutes ; aucun re-mint nécessaire — bien qu’une clé créée sur Free soit re-scopée lors de sa prochaine rotation.

Le body 429

Une requête qui dépasserait la limite renvoie 429 Too Many Requests avec un body plat au niveau supérieur — les payloads 429 structurés n’enveloppent pas les champs dans un objet detail (seuls les 429 avec string-detail comme map_load_hard_stop le font) :

{
  "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
}

Pour les endpoints de streaming, la limite est aussi exposée pendant le stream via un quota SSE event afin que votre UI puisse réagir avant la fin du stream.

Consultez Errors — Envelope pour la distinction complète entre les 429 plats et les versions encapsulées.

Dépasser l’allocation

Ce qui se passe au-delà de votre allocation dépend de votre forfait, et les deux cas sont volontairement différents.

Free s’arrête à l’allocation. Une requête qui la dépasserait renvoie 429 map_load_quota_exceeded. Cette limite définit le produit basemap gratuit.

Pro et Enterprise continuent de servir. Un dépassement sur un compte payant est une discussion de billing, pas une panne, vos embeds ne s’éteignent donc pas au milieu du mois — nous enregistrons le dépassement et faisons un suivi.

Cette tolérance n’est pas illimitée. Les forfaits payants s’arrêtent à cinq fois l’allocation avec 429 map_load_hard_stop. Aucun embed normal n’atteint ce niveau ; le plafond existe pour qu’une personne ayant copié une publishable key depuis le source de votre page ne puisse pas générer une facture illimitée à votre nom. Les packs de map-load achetés augmentent l’allocation, et le plafond évolue avec elle.

Si vous atteignez régulièrement la bande souple, vous avez besoin d’une allocation plus élevée plutôt que d’un contournement — contactez-nous.

Accès au basemap

Les designed basemaps font partie de votre compte Kaleidr, pas d’une tile API publique autonome : les embeds <kaleidr-map> et le SDK s’autorisent via votre publishable key (scope maps), et chaque map load — ouverture d’une shared-map, vue publiée/intégrée ou session basemap du SDK, environ 20 tile requests — consomme l’allocation mensuelle partagée décrite ci-dessus. L’utilisation directe par des tiers de tile.kaleidr.com hors d’un keyed embed est bloquée avec 429 et ce 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"
}

Le 429 comporte également un header Retry-After: 3600 — ne réessayez pas avant.

Si vous avez besoin de plus que l’allocation, contactez-nous — les volumes supérieurs sont accordés par organisation, et Enterprise peut servir depuis un CDN indépendant.

Rate limits et concurrence

Deux limites se trouvent devant le quota, et toutes deux rejettent l’excès avec un 429 plutôt que de le mettre en file d’attente :

• Requêtes par minute, par clé — fenêtre glissante de 60 secondes. Chaque clé possède son propre débit.
• Streams simultanés, par organisation — requêtes de streaming simultanées sur toutes les clés de votre organisation.

Réessayez avec backoff. Un 429 signifie ici "trop rapide pour le moment" ; un 429 contenant meter dans son body signifie que vous avez atteint le plafond mensuel.

Gestion

• Traitez 429 comme "ralentir / mettre à niveau", pas "cassé". Faites un backoff et réessayez.
• Affichez l’événement quota pendant le stream dans votre UI (budget restant).
• Consultez Errors pour le tableau complet des statuts.