Kontingente & Rate Limits

Eine Rechnung pro Organisation

Die Platform-Nutzung wird pro Organisation, nicht pro Schlüssel gemessen — jeder Schlüssel deiner Organisation verbraucht dasselbe gemeinsame Monatsbudget und sie teilen sich die Rate Limits. Ein Schlüssel, eine Rechnung: AI, Maps und Design belasten denselben Org-Meter.

Das Budget wird in einem monatlichen Kalenderzyklus zurückgesetzt.

Was dein Plan enthält

Der Plan deiner Organisation bestimmt sowohl, was ein Schlüssel erreichen kann, als auch das gemeinsame monatliche Token-Budget:

Plan	API surface	Monthly API tokens	Monthly map loads
Free	nur Basemaps — ein Publishable Key mit maps-Scope und tile-Produkt	n/a (kein ai-Scope)	50,000
Pro	vollständige Platform (ai, maps, design; Browser + Server Keys)	5,000,000	50,000
Enterprise	vollständige Platform	50,000,000	50,000

Jeder Plan hat dasselbe Map-Loads-Kontingent — Pläne unterscheiden sich bei Tokens, API-Oberfläche und Features. Enterprise-Volumen oberhalb des Kontingents werden pro Organisation erhöht, nicht über eine höhere Plan-Stufe.

Free-Plan-Keys bedienen Basemap-Embeds, die als Map Loads statt als Tokens gemessen werden. Für AI- und Design-Oberflächen upgrade unter kaleidr.com/billing. Planänderungen gelten innerhalb weniger Minuten für deine bestehenden Schlüssel; kein Re-Mint erforderlich — ein auf Free erstellter Schlüssel wird jedoch bei der nächsten Rotation neu gescoped.

Der 429-Body

Eine Anfrage, die das Limit überschreiten würde, gibt 429 Too Many Requests mit einem flachen Top-Level-Body zurück — strukturierte 429-Payloads kapseln Felder nicht in einem detail-Objekt (nur String-Detail-429er wie map_load_hard_stop tun dies):

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

Bei Streaming-Endpoints wird das Limit außerdem während des Streams als quota SSE event ausgegeben, damit deine UI reagieren kann, bevor der Stream endet.

Siehe Errors — Envelope für die vollständige Unterscheidung zwischen flachen 429ern und gekapselten Varianten.

Überschreiten des Kontingents

Was oberhalb deines Kontingents passiert, hängt vom Plan ab; die beiden Fälle sind bewusst unterschiedlich.

Free stoppt am Kontingent. Eine Anfrage, die darüber hinausgehen würde, gibt 429 map_load_quota_exceeded zurück. Diese Grenze definiert das kostenlose Basemap-Produkt.

Pro und Enterprise liefern weiter. Eine Überschreitung auf einem zahlenden Konto ist ein Billing- Thema, kein Ausfall; deine Embeds werden daher nicht mitten im Monat dunkel — wir zeichnen die Überschreitung auf und melden uns.

Diese Kulanz ist nicht unbegrenzt. Bezahlte Pläne stoppen bei dem Fünffachen des Kontingents mit 429 map_load_hard_stop. Kein normaler Embed erreicht das; die Obergrenze existiert, damit jemand, der einen Publishable Key aus deinem Seitenquelltext kopiert, keine unbegrenzte Rechnung in deinem Namen erzeugen kann. Gekaufte Map-Load-Pakete erhöhen das Kontingent und die Obergrenze skaliert mit.

Wenn du regelmäßig den Soft-Bereich erreichst, brauchst du mehr Kontingent statt eines Workarounds — kontaktiere uns.

Basemap-Zugriff

Die designed basemaps sind Teil deines Kaleidr-Kontos, keine eigenständige öffentliche Tile-API: <kaleidr-map>-Embeds und das SDK autorisieren über deinen Publishable Key (maps-Scope), und jeder Map Load — ein Shared-Map- Open, eine veröffentlichte/eingebettete Ansicht oder eine SDK-Basemap-Session, etwa 20 Tile- Requests — wird vom gemeinsamen Monatskontingent abgezogen. Direkte Drittanbieternutzung von tile.kaleidr.com außerhalb eines keyed embed wird mit 429 und diesem Body blockiert:

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

Der 429 enthält außerdem einen Header Retry-After: 3600 — nicht früher erneut versuchen.

Wenn du mehr als das Kontingent benötigst, kontaktiere uns — höhere Volumen werden pro Organisation freigegeben und Enterprise kann über ein unabhängiges CDN ausliefern.

Rate Limits und Parallelität

Zwei Limits liegen vor dem Kontingent; beide verwerfen Überschüsse mit 429, statt sie in eine Warteschlange zu stellen:

• Requests pro Minute, pro Schlüssel — gleitendes 60-Sekunden-Fenster. Jeder Schlüssel hat seine eigene Rate.
• Gleichzeitige Streams, pro Organisation — simultane Streaming-Anfragen über alle Schlüssel deiner Organisation.

Mit Backoff erneut versuchen. Ein 429 bedeutet hier "gerade zu schnell"; ein 429 mit meter im Body bedeutet, dass du das Monatslimit erreicht hast.

Umgang damit

• Behandle 429 als "langsamer / upgraden", nicht als "kaputt". Backoff und erneut versuchen.
• Zeige das quota-Event während des Streams in deiner UI an (verbleibendes Budget).
• Siehe Errors für die vollständige Status-Tabelle.