Quotas et limites de débit

Kaleidr limite l’utilisation de deux façons différentes. Dans les deux cas, la réponse porte le statut HTTP 429 :

• Le quota détermine ce que votre organisation peut consommer pendant une période de facturation. Lorsqu’il est épuisé, il faut attendre le renouvellement de la période ou ajouter des ressources.
• Les limites de débit déterminent la vitesse à laquelle vous pouvez envoyer des appels. Lorsqu’une limite est atteinte, ralentissez pendant quelques secondes.

Le corps de la réponse permet de savoir quelle limite a été atteinte. Cette page présente chaque format de réponse, le coût de chaque appel et la manière de traiter chaque situation.

Les deux réserves de ressources

L’utilisation est comptabilisée par organisation, dans deux réserves.

Réserve	Ce qui la consomme	Free	Pro	Enterprise
Crédits IA	Réponses du chat, recherches de lieux, recherches d’adresses et analyses de conception	500,000 par période	5,000,000 par période	Montant personnalisé, fixé par contrat
Chargements de cartes	Chaque session Tile et chaque affichage d’une carte publiée ou intégrée	50,000 par période	50,000 par période	Même allocation de base ; volumes supérieurs définis par contrat

Trois points concernant ces réserves prêtent souvent à confusion :

• Les crédits IA forment une seule réserve pour toute l’organisation. Vos clés API puisent dans les mêmes crédits IA que ceux utilisés par votre équipe dans les applications Kaleidr. Il n’existe pas de budget API distinct : toutes les clés partagent cette réserve.
• La période est votre période de facturation. Pour un abonnement payant, il s’agit du cycle mensuel commençant le jour de votre souscription. Sans abonnement, c’est le mois civil. Les périodes se renouvellent à minuit, heure de l’Est des États-Unis.
• Les packs augmentent la limite. Les packs de crédits IA et de chargements de cartes achetés s’ajoutent à l’allocation du forfait et sont compris dans le champ limit des réponses.

Les changements de forfait s’appliquent aux clés existantes en quelques minutes. Vous n’avez pas besoin de créer de nouvelles clés.

Coût de chaque appel

Appel	Réserve	Coût
POST /chat/control/stream, /chat/summary/stream, /chat/button/stream, /spot/overview/stream	Crédits IA	Les tokens utilisés pour la réponse, en entrée et en sortie. Voir Facturation d’un flux.
POST /chat/control/route	aucune	Gratuit. Une réserve temporaire est constituée pendant le calcul de l’itinéraire, puis toujours libérée.
POST /spot	Crédits IA	Montant forfaitaire par appel, qu’un résultat soit trouvé ou non : le coût de /retrieval/poi/enrich si want comprend content ou photos et que le contenu est récupéré pour cet appel, sinon celui de /retrieval/geocode/forward si address est demandé. Le contenu déjà récupéré pour une requête précédente ne coûte rien. Un appel ne demandant que des lieux, des régions et des contours est gratuit.
GET /retrieval/poi/enrich	Crédits IA	Montant forfaitaire par appel, même si aucun contenu n’est trouvé.
GET /retrieval/geocode/forward	Crédits IA	Montant forfaitaire inférieur par appel, même sans résultat. Aucun coût si la recherche elle-même échoue.
POST /design/analyze	Crédits IA	Montant forfaitaire par appel réussi. Gratuit en cas d’échec.
POST /design/apply-direct, GET /design/styles, /design/samples, /design/themes	aucune	Gratuit.
POST /sdk/sessions pour chat, editor, viewer	aucune	Gratuit.
POST /sdk/sessions pour tile	Chargements de cartes	Un chargement de carte par échange de session.
POST /sdk/share-sessions	aucune	Gratuit. Les appels de chat utilisant la session sont facturés à l’organisation propriétaire de la carte.
POST /inference-api/vendor/mapping/propose, la proposition de correspondance de l’API de téléversement des données métier	Crédits IA	Les tokens utilisés pour la proposition. Cet appel utilise une connexion à un compte, pas une clé API. Si les crédits sont épuisés, il renvoie 429 quota_exceeded. Il est également limité à 30 propositions par compte et par heure ; les deux réponses 429 ont des formats différents. Téléverser, publier, dépublier et supprimer des données est gratuit.

Votre utilisation actuelle et vos limites sont disponibles sur kaleidr.com/billing.

Facturation d’un flux

Le coût d’un appel en flux n’est connu qu’une fois celui-ci terminé. Il est donc facturé en deux étapes :

1. Réservation. Lorsqu’une requête est acceptée, un nombre fixe de crédits est réservé dans la réserve. Si elle ne peut pas couvrir cette réservation, la requête est refusée avec quota_exceeded avant qu’une réponse ne soit produite. Un appel nécessite donc un peu de crédits disponibles pour commencer, même si son coût final aurait été inférieur.
2. Règlement. À la fin du flux, la réservation est remplacée par le coût réel : les tokens utilisés par la réponse. Ce coût peut être supérieur ou inférieur à la réservation.

Si vous interrompez un flux, ou s’il échoue avant la fin de la réponse, le nombre de tokens est inconnu et le coût est estimé :

Flux	Coût lorsqu’il se termine sans aboutir
/chat/control/stream	Le plus élevé des deux montants suivants : une estimation de la conversation envoyée (les messages user et assistant de la requête) ou une estimation du texte déjà transmis, comptabilisée jusqu’à la réservation. Le coût peut dépasser la réservation.
/chat/summary/stream, /chat/button/stream, /spot/overview/stream	Une estimation du texte déjà transmis, jamais supérieure à la réservation.

Fermer prématurément un flux de chat ne rend donc pas gratuite une longue conversation : au minimum, la taille de la requête elle-même est facturée, quelle que soit la quantité de réponse lue. Limitez la taille des requêtes en n’envoyant que les échanges nécessaires à la prochaine réponse. Voir Lecture d’un flux.

Atteindre une limite pendant l’exécution d’un flux ne l’interrompt pas. Le contrôle a lieu à l’admission : c’est la requête suivante qui sera refusée.

Une requête refusée n’est pas facturée. Une requête rejetée avant son traitement (limite de débit ou de simultanéité, erreur de validation, corps trop volumineux) ne conserve ensuite ni crédits IA réservés ni place de traitement simultané. Vous pouvez recommencer sans avoir payé pour le refus.

Plafond propre à une clé

Une clé peut disposer d’un plafond mensuel (monthly_cap_tokens, défini via l’API de gestion des clés). Il limite les crédits IA que cette clé peut consommer dans la réserve de l’organisation pendant une période. Le plafond de la réserve de l’organisation reste la limite globale.

Une requête qui ferait dépasser à une clé son propre plafond est refusée avec le même corps quota_exceeded. Les champs limit et used indiquent alors les valeurs de la clé et non celles de la réserve.

Quota dépassé

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

{
  "error": "quota_exceeded",
  "detail": "Usage limit reached. Please try again later.",
  "product": "b2b",
  "meter": "b2b.tokens",
  "tier": "pro",
  "limit": 5000000,
  "used": 4999100,
  "remaining": 900,
  "reset_at": "2026-11-01T04:00:00+00:00",
  "period": "month",
  "reset_in_seconds": 1296000
}

Champ	Signification
error	Toujours quota_exceeded dans ce cas. Utilisez ce champ pour orienter la logique de traitement.
detail	Une phrase destinée à l'utilisateur. Ne l'analysez pas par programme.
product, meter	Identifient le compteur de crédits d'IA de l'API. Pour les clés de plateforme, les valeurs sont toujours b2b et b2b.tokens.
tier	L'abonnement de votre organisation.
limit, used, remaining	Les montants en crédits du quota partagé, ou ceux de la clé lorsque l'appel est refusé en raison d'un plafond propre à celle-ci. remaining peut être supérieur à zéro : l'appel a été refusé car la réservation provisoire ne pouvait pas être couverte.
reset_at	La fin de la période, sous forme d'horodatage ISO 8601 avec décalage horaire. Utilisez cette valeur pour informer l'utilisateur de la reprise du service.
period	month.
reset_in_seconds	Nombre de secondes jusqu'à reset_at, la fin de la période à laquelle votre quota est réinitialisé (votre cycle d'abonnement ou, à défaut, le mois civil). L'en-tête Retry-After contient la même valeur.

Le corps de la réponse est plat : ses champs sont au niveau racine et non dans un objet detail.

Avec un jeton de session

Le corps décrit ci-dessus est celui que reçoit une clé serveur ou une ancienne clé. Une requête effectuée avec un jeton de session s’exécute dans le navigateur d’un visiteur. En cas de refus, elle ne révèle donc ni le forfait, ni l’utilisation, ni le plafond de l’organisation. Cela vaut pour les sessions échangées depuis une clé publiable et pour les sessions des visiteurs d’une carte publiée.

{
  "error": "quota_exceeded",
  "detail": "Usage limit reached. Please try again later.",
  "meter": "b2b.tokens",
  "reset_at": "2026-11-01T04:00:00+00:00",
  "reset_in_seconds": 1296000
}

Champ	Clé serveur ou ancienne clé	Jeton de session
error, detail	Oui	Oui
meter	Oui	Oui
reset_at, reset_in_seconds	Oui	Oui
product, period	Oui	Non
tier	Oui	Non
limit, used, remaining	Oui	Non

Le statut, l’en-tête Retry-After et leur signification sont identiques. Dans le code du navigateur, vérifiez error et affichez reset_at ; n’essayez pas de lire limit, used ou remaining. Pour afficher des chiffres d’utilisation, obtenez-les depuis votre backend avec une clé serveur ou sur kaleidr.com/billing.

Si le corps indique used: 0 alors que vous savez que l’organisation a déjà utilisé le service, l’API n’a pas pu lire les données d’utilisation et a refusé la requête par précaution. Réessayez après quelques secondes plutôt que d’attendre reset_at.

Limites de débit et simultanéité

Trois limites sont vérifiées avant chaque appel d’exécution. Les requêtes excédentaires sont refusées immédiatement ; aucune n’est mise en file d’attente.

Limite	Comptabilisée par	Périmètre
Requêtes par minute	Clé	Fenêtre glissante de 60 secondes couvrant chaque appel d’exécution avec la clé et toutes les sessions échangées depuis cette clé. Tous les visiteurs d’un site utilisant une même clé publiable partagent ce budget.
Échanges de session par minute	Clé	Appels à POST /sdk/sessions. Ils disposent d’un budget séparé ; monter des composants intégrés ne consomme donc pas les appels d’exécution.
Requêtes simultanées	Organisation	Appels en cours au même instant sur l’ensemble des clés de l’organisation. Un flux compte tant qu’il reste ouvert.

Le nombre de requêtes par minute d’une clé ne peut pas être modifié sur la page des clés API ou par l’API de gestion des clés. Si votre trafic exige une limite supérieure, contactez-nous.

Tous ces refus suivent le même format et comportent le même en-tête :

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

{ "error": "rate_limited", "detail": "API key rate limit exceeded. Slow down." }

error	Signification	Action à effectuer
rate_limited	Le budget de requêtes par minute ou d’échanges de session de la clé est épuisé.	Attendre le nombre de secondes indiqué par Retry-After, puis réessayer. Ajouter un décalage aléatoire.
org_overloaded	Trop d’appels sont en cours dans votre organisation.	Attendre la fin d’un des appels ouverts, puis réessayer. Fermer les flux inutiles.
b2b_overloaded	L’API a atteint sa capacité pour l’ensemble des utilisateurs.	Attendre Retry-After secondes, puis réessayer avec des délais croissants.
limiter_unavailable	Le système de limitation de débit n’a pas pu répondre.	Réessayer rapidement. Ralentir ne sert à rien ; ce problème n’est pas lié à votre débit.
visitor_limit_reached	Un visiteur du chat d’une carte publiée a dépassé son nombre de requêtes par minute ou par jour.	Afficher un message invitant le visiteur à réessayer plus tard. Voir Chat sur une carte publiée.

Les requêtes sont aussi soumises à des limites de débit à la périphérie du réseau, par adresse IP et par identifiant d’accès. Une requête bloquée à ce niveau ne contient aucun des corps JSON décrits sur cette page. Traitez une réponse 4xx sans corps Kaleidr comme une indication de ralentir et de réessayer plus tard.

Chargements de cartes

Un chargement de carte est comptabilisé chaque fois qu’une carte Kaleidr démarre pour un visiteur :

• chaque échange de session pour product: "tile", y compris son renouvellement par le SDK et chaque remontage de l’élément ;
• chaque affichage d’une carte publiée ou intégrée.

L’échange de session de l’éditeur intégré ne compte pas comme un chargement de carte. À la place, ses requêtes de fond de carte portant votre clé publiable (style, sprites et polices) sont comptabilisées par lots : chaque groupe de 20 requêtes de votre organisation sur une heure ajoute après coup un chargement de carte. Elles ne sont jamais refusées en raison de l’allocation. Les données des tuiles elles-mêmes ne sont pas comptabilisées.

Chaque forfait s’arrête à son allocation. Lorsque la réserve est épuisée, le chargement suivant est refusé et n’est pas comptabilisé. Il n’existe aucune marge supplémentaire sur les forfaits payants ; l’achat d’un pack de chargements de cartes augmente immédiatement la limite.

Lors de l’échange de session, le refus se présente ainsi :

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

{ "detail": "map_load_quota_exceeded" }

Ce corps est encapsulé dans detail, contrairement au corps plat de quota ci-dessus, et ne comporte pas d’en-tête Retry-After. Réessayer ne sert à rien avant le renouvellement de la période ou l’ajout d’un pack. Sur la page, le composant Tile intégré ne démarre pas et le SDK journalise kaleidr session exchange failed (429).

Requêtes directes de tuiles

L’hôte des tuiles du fond de carte n’est pas une API publique de tuiles. La méthode prise en charge pour afficher un fond de carte Kaleidr est le produit Tile. Toute requête adressée à tile.kaleidr.com qui ne provient pas d’un composant Kaleidr intégré avec une clé publiable valide sur une origine autorisée est refusée :

HTTP/1.1 429 Too Many Requests
Retry-After: 3600
Cache-Control: no-store
Content-Type: application/json

{
  "error": "tile_access_restricted",
  "message": "Direct access to tile.kaleidr.com requires a Kaleidr publishable key. Mint a free one at kaleidr.com/api-keys and pass it as ?key= from an allowed origin. Kaleidr-hosted maps and embeds are unaffected.",
  "docs": "https://docs.kaleidr.com/get-an-api-key"
}

Cette réponse vient de l’hôte des tuiles, et non de l’API de plateforme. Elle utilise donc message là où l’API utilise detail. Une clé récemment créée ou modifiée peut prendre quelques minutes avant d’être acceptée pour les tuiles.

L’événement quota dans un flux

Un flux de chat indique l’état de la réserve après facturation. L’événement quota est le dernier événement du flux, envoyé après end ou error :

event: quota
data: {"type": "quota", "product": "b2b", "meter": "b2b.tokens", "tier": "pro", "used": 184223, "limit": 5000000, "reset_at": "2026-11-01T04:00:00+00:00", "period": "month"}

C’est l’événement d’un flux lu avec une clé serveur ou une ancienne clé. Pour un flux lu avec un jeton de session (échangé depuis une clé publiable, ou session d’un visiteur d’une carte publiée), l’événement ne contient ni forfait ni chiffres :

event: quota
data: {"type": "quota", "meter": "b2b.tokens", "reset_at": "2026-11-01T04:00:00+00:00"}

Champ	Clé serveur ou ancienne clé	Jeton de session
type, meter, reset_at	Oui	Oui
product, period	Oui	Non
tier	Oui	Non
used, limit	Oui	Non

Avec une clé serveur, utilisez cet événement pour actualiser un indicateur de consommation sans nouvelle requête. Trois restrictions s’appliquent :

• Il n’y a pas de champ remaining. Calculez limit - used.
• L’événement est envoyé dans la mesure du possible. Un flux peut se terminer sans cet événement : n’attendez donc pas sa réception.
• Il informe, mais n’avertit pas. Il n’arrive jamais au milieu d’une réponse et ne peut pas interrompre un flux.

Pour le recevoir, continuez à lire jusqu’à la fermeture du corps de la réponse. Un client qui s’arrête à end le manquera.

Gestion du code 429

Lisez le corps avant de décider. Le statut seul ne suffit pas à déterminer si une nouvelle tentative est appropriée.

Réponse reçue	Réessayer ?	Quand
error: "quota_exceeded"	Non	Après reset_at, ou après ajout de crédits ou relèvement du plafond de la clé. Afficher un message indiquant que la limite est atteinte.
error: "rate_limited", "org_overloaded", "b2b_overloaded", "limiter_unavailable"	Oui	Après le nombre de secondes indiqué par Retry-After, avec un décalage aléatoire, quelques tentatives au maximum.
error: "visitor_limit_reached"	Non	Plus tard ; en informer le visiteur.
detail: "map_load_quota_exceeded"	Non	Après le renouvellement de la période ou l’ajout d’un pack de chargements de cartes.
error: "tile_access_restricted"	Non	Corriger le composant intégré : utiliser le produit Tile avec une clé publiable sur une origine autorisée.

const RETRYABLE = new Set(['rate_limited', 'org_overloaded', 'b2b_overloaded', 'limiter_unavailable']);

async function callKaleidr(url, init, attempt = 0) {
  const res = await fetch(url, init);
  if (res.status !== 429) return res;

  const body = await res.json().catch(() => ({}));
  if (RETRYABLE.has(body.error) && attempt < 3) {
    const seconds = Number(res.headers.get('retry-after')) || 5;
    await new Promise((resolve) => setTimeout(resolve, (seconds + Math.random()) * 1000));
    return callKaleidr(url, init, attempt + 1);
  }

  const error = new Error(body.error || body.detail || 'rate limited');
  error.status = 429;
  error.code = body.error || body.detail;
  error.resetAt = body.reset_at; // present for quota_exceeded
  throw error;
}

Dans le navigateur, JavaScript peut lire l’en-tête Retry-After des réponses de l’API de plateforme.

Pages associées

• Erreurs : tous les statuts et codes.
• Contrat SSE : emplacement de l’événement quota dans un flux.
• Lecture d’un flux : clients complets avec gestion des nouvelles tentatives et des délais d’attente.
• Obtenir une clé API : contenu de chaque forfait.