Kontingente und Ratenbegrenzungen

Kaleidr begrenzt die Nutzung auf zwei unterschiedliche Arten. Beide führen zum HTTP-Status 429:

• Kontingent bezeichnet die Nutzung, die Ihrer Organisation innerhalb eines Abrechnungszeitraums zusteht. Ist es aufgebraucht, müssen Sie auf die Zurücksetzung warten oder zusätzliches Kontingent erwerben.
• Ratenbegrenzungen legen fest, wie schnell Sie Anfragen senden dürfen. Beim Erreichen einer Grenze müssen Sie einige Sekunden langsamer vorgehen.

Am Antwortinhalt erkennen Sie, welche Grenze erreicht wurde. Diese Seite zeigt die Antwortformate, die Kosten der einzelnen Aufrufe und die passende Behandlung.

Die beiden Kontingentpools

Die Nutzung wird pro Organisation in zwei Pools erfasst.

Pool	Was den Pool verbraucht	Free	Pro	Enterprise
KI-Credits	Chatantworten, Ortsabfragen, Adresssuche, Designanalyse	500.000 pro Zeitraum	5.000.000 pro Zeitraum	Individuell im Vertrag festgelegt
Kartenladungen	Jede Tile-Sitzung sowie jeder Aufruf einer veröffentlichten oder eingebetteten Karte	50.000 pro Zeitraum	50.000 pro Zeitraum	Derselbe Grundfreibetrag; höhere Volumina werden vertraglich vereinbart

Drei Punkte zu diesen Pools werden häufig missverstanden:

• KI-Credits bilden einen gemeinsamen Pool für die gesamte Organisation. Ihre API-Schlüssel verwenden dieselben KI-Credits wie Ihr Team in den Kaleidr-Anwendungen. Es gibt kein separates API-Budget; alle Schlüssel teilen sich den Pool.
• Der Zeitraum entspricht Ihrem Abrechnungszeitraum. Bei einem kostenpflichtigen Abonnement ist dies der monatliche Zyklus ab dem Tag des Abschlusses. Ohne Abonnement gilt der Kalendermonat. Der Wechsel erfolgt um Mitternacht nach US-Ostküstenzeit.
• Pakete erhöhen die Grenze. Gekaufte Pakete mit KI-Credits oder Kartenladungen kommen zum Tarifkontingent hinzu und sind im Antwortfeld limit enthalten.

Tarifänderungen werden innerhalb weniger Minuten für Ihre bestehenden Schlüssel wirksam. Neue Schlüssel sind nicht erforderlich.

Kosten der einzelnen API-Aufrufe

Aufruf	Pool	Kosten
POST /chat/control/stream, /chat/summary/stream, /chat/button/stream, /spot/overview/stream	KI-Credits	Die für die Antwort verwendeten Tokens, Eingabe plus Ausgabe. Siehe Abrechnung eines Streams.
POST /chat/control/route	keiner	Kostenlos. Während der Routenberechnung wird ein Betrag reserviert und anschließend immer wieder freigegeben.
POST /spot	KI-Credits	Pauschale pro Aufruf, auch wenn nichts gefunden wird: die Gebühr für /retrieval/poi/enrich, wenn want content oder photos enthält und der Inhalt für diesen Aufruf abgerufen wird; andernfalls die Gebühr für /retrieval/geocode/forward, wenn address angefordert wird. Bereits für eine frühere Anfrage abgerufene Inhalte kosten nichts. Eine reine Abfrage von Orten, Regionen und Umrissen ist kostenlos.
GET /retrieval/poi/enrich	KI-Credits	Pauschale pro Aufruf, auch ohne gefundenen Inhalt.
GET /retrieval/geocode/forward	KI-Credits	Geringere Pauschale pro Aufruf, auch bei leeren Ergebnissen. Schlägt die Suche selbst fehl, wird nichts berechnet.
POST /design/analyze	KI-Credits	Pauschale pro erfolgreichem Aufruf. Bei einem Fehler kostenlos.
POST /design/apply-direct, GET /design/styles, /design/samples, /design/themes	keiner	Kostenlos.
POST /sdk/sessions für chat, editor, viewer	keiner	Kostenlos.
POST /sdk/sessions für tile	Kartenladungen	Eine Kartenladung pro Sitzungsaustausch.
POST /sdk/share-sessions	keiner	Kostenlos. Die Chat-Aufrufe mit dieser Sitzung werden dem Karteneigentümer berechnet.
POST /inference-api/vendor/mapping/propose, der Zuordnungsvorschlag der API für das Hochladen von Geschäftsdaten	KI-Credits	Die Tokens des Vorschlags. Der Aufruf erfolgt mit einer Kontoanmeldung, nicht mit einem API-Schlüssel. Sind die Credits aufgebraucht, wird 429 quota_exceeded zurückgegeben. Zusätzlich gilt ein Limit von 30 Vorschlägen pro Konto und Stunde; die beiden 429-Antworten haben unterschiedliche Formate. Hochladen, Veröffentlichen, Zurückziehen einer Veröffentlichung und Löschen sind kostenlos.

Ihre aktuelle Nutzung und die Grenzen finden Sie unter kaleidr.com/billing.

Abrechnung eines Streams

Die Kosten eines Streaming-Aufrufs stehen erst nach dessen Abschluss fest. Deshalb erfolgt die Abrechnung in zwei Schritten:

1. Reservierung. Sobald eine Anfrage angenommen wird, reserviert das System eine feste Anzahl Credits im Pool. Reicht der Pool dafür nicht aus, wird die Anfrage mit quota_exceeded abgelehnt, noch bevor eine Antwort erzeugt wird. Ein Aufruf benötigt daher ausreichend freie Credits, selbst wenn die tatsächlichen Kosten geringer wären.
2. Endabrechnung. Nach Ende des Streams wird die Reservierung durch die tatsächlichen Kosten ersetzt: die für die Antwort verwendeten Tokens. Diese können über oder unter der Reservierung liegen.

Wenn Sie einen Stream abbrechen oder er vor Abschluss der Antwort fehlschlägt, ist die Tokenzahl unbekannt. Die Abrechnung erfolgt dann anhand einer Schätzung:

Stream	Abrechnung bei vorzeitigem Ende
/chat/control/stream	Es gilt der höhere Wert aus einer Schätzung der gesendeten Unterhaltung (die user- und assistant-Nachrichten der Anfrage) und einer Schätzung des bereits gestreamten Texts, die bis zur Höhe der Reservierung erfasst wird. Die Kosten können die Reservierung übersteigen.
/chat/summary/stream, /chat/button/stream, /spot/overview/stream	Schätzung des bereits gestreamten Texts, höchstens in Höhe der Reservierung.

Ein frühzeitig geschlossener Chat-Stream macht eine lange Unterhaltung daher nicht kostenlos: Mindestens die Größe der gesendeten Anfrage wird berechnet, unabhängig davon, wie wenig Antwort Sie gelesen haben. Halten Sie Anfragen klein und senden Sie nur die für die nächste Antwort benötigten Gesprächszüge. Siehe Stream lesen.

Wird eine Grenze während eines laufenden Streams erreicht, wird dieser nicht unterbrochen. Die Prüfung erfolgt bei Annahme der Anfrage; erst die nächste Anfrage wird abgelehnt.

Abgelehnte Anfragen werden nicht berechnet. Wird eine Anfrage vor der Verarbeitung abgelehnt (wegen Raten- oder Parallelitätsgrenzen, Validierungsfehlern oder zu großem Request-Body), bleiben anschließend weder KI-Credits noch ein Parallelitätsplatz reserviert. Sie können den Aufruf wiederholen, ohne für die Ablehnung bezahlt zu haben.

Individuelle Grenze für einen Schlüssel

Ein Schlüssel kann eine monatliche Obergrenze erhalten (monthly_cap_tokens, eingestellt über die Schlüsselverwaltungs-API). Sie begrenzt, wie viele KI-Credits dieser Schlüssel in einem Zeitraum aus dem Organisationspool verbrauchen darf. Die Grenze des Organisationspools gilt weiterhin zusätzlich.

Eine Anfrage, mit der ein begrenzter Schlüssel seine Obergrenze überschreiten würde, wird mit demselben quota_exceeded-Antwortformat abgelehnt. Dabei zeigen limit und used die Werte des Schlüssels statt die des gesamten Pools an.

Kontingent überschritten

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
}

Feld	Bedeutung
error	In diesem Fall immer quota_exceeded. Verzweigen Sie die Programmlogik anhand dieses Felds.
detail	Ein für Menschen formulierter Satz. Nicht programmatisch auswerten.
product, meter	Kennzeichnen den Zähler für KI-Guthaben der API. Bei Plattformschlüsseln immer b2b und b2b.tokens.
tier	Der Tarif Ihrer Organisation.
limit, used, remaining	Die Guthabenwerte des Pools beziehungsweise die Werte des Schlüssels, wenn ein schlüsselbezogenes Limit die Anfrage abgewiesen hat. remaining kann größer als null sein: Die Anfrage wurde abgewiesen, weil die vorläufige Reservierung nicht mehr hineinpasste.
reset_at	Das Ende des Abrechnungszeitraums als ISO-8601-Zeitstempel mit Zeitzonenoffset. Verwenden Sie diesen Wert, um Nutzern mitzuteilen, wann der Dienst wieder verfügbar ist.
period	month.
reset_in_seconds	Sekunden bis reset_at, also bis zum Ende des Zeitraums, in dem sich Ihr Pool zurücksetzt (Ihr Abonnementzyklus oder ohne Abonnement der Kalendermonat). Der Header Retry-After enthält denselben Wert.

Der Antwort-Body ist flach aufgebaut: Alle Felder stehen auf oberster Ebene, nicht innerhalb eines detail-Objekts.

Mit einem Sitzungstoken

Das oben gezeigte Antwortformat gilt für einen Serverschlüssel oder Legacy-Schlüssel. Eine Anfrage mit einem Sitzungstoken wird im Browser eines Besuchers ausgeführt. Deshalb verrät eine Ablehnung weder den Tarif noch die Nutzung oder die Obergrenze der Organisation. Dies gilt sowohl für Sitzungen, die aus einem veröffentlichbaren Schlüssel erzeugt wurden, als auch für Besuchersitzungen einer veröffentlichten Karte.

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

Feld	Serverschlüssel oder Legacy-Schlüssel	Sitzungstoken
error, detail	Ja	Ja
meter	Ja	Ja
reset_at, reset_in_seconds	Ja	Ja
product, period	Ja	Nein
tier	Ja	Nein
limit, used, remaining	Ja	Nein

Status, Header Retry-After und Bedeutung sind identisch. Prüfen Sie im Browsercode error und zeigen Sie reset_at an; lesen Sie nicht limit, used oder remaining. Nutzungszahlen erhalten Sie auf Ihrem Backend mit einem Serverschlüssel oder unter kaleidr.com/billing.

Wenn der Antwort-Body used: 0 anzeigt, obwohl Ihre Organisation bereits aktiv war, konnte die API die Nutzung nicht abrufen und hat den Aufruf vorsichtshalber abgelehnt. Versuchen Sie es nach einigen Sekunden erneut, statt bis reset_at zu warten.

Ratenbegrenzungen und parallele Anfragen

Vor jedem Laufzeitaufruf werden drei Grenzen geprüft. Überschüssige Anfragen werden sofort abgelehnt und nicht in eine Warteschlange gestellt.

Grenze	Zählung pro	Geltungsbereich
Anfragen pro Minute	Schlüssel	Gleitendes 60-Sekunden-Fenster für jeden Laufzeitaufruf mit dem Schlüssel und allen daraus ausgestellten Sitzungen. Alle Besucher einer Website mit demselben veröffentlichbaren Schlüssel teilen sich dieses Budget.
Sitzungsaustausche pro Minute	Schlüssel	Aufrufe von POST /sdk/sessions. Dafür gilt ein eigenes Budget; das Einbinden von Embeds verbraucht daher keine Laufzeitaufrufe.
Parallele Anfragen	Organisation	Alle gleichzeitig laufenden Aufrufe über sämtliche Schlüssel der Organisation. Ein Stream zählt, solange er geöffnet ist.

Der Wert für Anfragen pro Minute eines Schlüssels lässt sich weder auf der API-Keys-Seite noch über die Schlüsselverwaltungs-API ändern. Benötigen Sie für Ihr Anfragevolumen ein höheres Limit, kontaktieren Sie uns.

Alle diese Ablehnungen verwenden dasselbe Antwortformat und denselben Header:

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	Bedeutung	Was zu tun ist
rate_limited	Das Budget für Anfragen oder Sitzungsaustausche pro Minute des Schlüssels ist ausgeschöpft.	Die in Retry-After angegebenen Sekunden warten und erneut versuchen. Zufällige Verzögerung hinzufügen.
org_overloaded	In Ihrer Organisation laufen zu viele Anfragen gleichzeitig.	Warten, bis einer der offenen Aufrufe abgeschlossen ist, und dann erneut versuchen. Nicht mehr benötigte Streams schließen.
b2b_overloaded	Die API hat für alle Nutzer ihre Kapazitätsgrenze erreicht.	Nach Retry-After Sekunden mit schrittweise längeren Wartezeiten erneut versuchen.
limiter_unavailable	Die Ratenbegrenzung konnte nicht antworten.	Kurz darauf erneut versuchen. Langsamer zu senden hilft nicht, da dies kein Problem Ihrer Anfragerate ist.
visitor_limit_reached	Ein Besucher des Chats einer veröffentlichten Karte hat pro Minute oder Tag zu viele Anfragen gestellt.	Dem Besucher anzeigen, dass er es später erneut versuchen soll. Siehe Chat auf einer veröffentlichten Karte.

Zusätzlich werden Anfragen am Netzwerkrand anhand der IP-Adresse und der Zugangsdaten begrenzt. Eine dort blockierte Anfrage enthält keines der auf dieser Seite beschriebenen JSON-Antwortformate. Behandeln Sie eine 4xx-Antwort ohne Kaleidr-Body so, dass Sie zunächst langsamer vorgehen und später erneut versuchen.

Kartenladungen

Eine Kartenladung wird jedes Mal gezählt, wenn eine Kaleidr-Karte für einen Betrachter gestartet wird:

• jeder Sitzungsaustausch für product: "tile", einschließlich der Aktualisierung durch das SDK und jedes erneuten Einbindens des Elements;
• jeder Aufruf einer veröffentlichten oder eingebetteten Karte.

Der Sitzungsaustausch des eingebetteten Editors gilt nicht als Kartenladung. Dessen Basiskartenanfragen, die Ihren veröffentlichbaren Schlüssel enthalten (Stil, Sprites und Schriftarten), werden stattdessen gesammelt abgerechnet: Je 20 dieser Anfragen, die Ihre Organisation innerhalb einer Stunde sendet, kommen nachträglich als eine Kartenladung hinzu. Diese Anfragen werden wegen des Kontingents niemals abgelehnt. Die Kartentile-Daten selbst werden nicht gezählt.

Jeder Tarif stoppt bei seinem Kontingent. Sobald der Pool aufgebraucht ist, wird die nächste Kartenladung abgelehnt und nicht gezählt. In kostenpflichtigen Tarifen gibt es keine zusätzliche Toleranzspanne; ein gekauftes Kartenladungspaket erhöht die Grenze sofort.

Beim Sitzungsaustausch sieht die Ablehnung so aus:

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

{ "detail": "map_load_quota_exceeded" }

Anders als die obige flache Kontingentantwort ist dieser Body in detail gekapselt und enthält keinen Header Retry-After. Erneute Versuche helfen erst nach der Zurücksetzung des Zeitraums oder dem Kauf eines Pakets. Auf der Website startet das Tile-Embed nicht und das SDK protokolliert kaleidr session exchange failed (429).

Direkte Tile-Anfragen

Der Host für Basiskarten-Tiles ist keine öffentliche Tile-API. Unterstützt wird die Anzeige einer Kaleidr-Basiskarte über das Tile-Produkt. Anfragen an tile.kaleidr.com werden abgelehnt, wenn sie nicht von einem Kaleidr-Embed mit gültigem veröffentlichbarem Schlüssel auf einem zugelassenen Ursprung stammen:

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

Diese Antwort stammt vom Tile-Host, nicht von der Plattform-API. Deshalb verwendet sie message statt des API-Felds detail. Ein neu erstellter oder bearbeiteter Schlüssel kann erst nach einigen Minuten für Tiles zugelassen sein.

Das Ereignis quota in einem Stream

Ein Chat-Stream meldet den Pool nach erfolgter Abrechnung. Das Ereignis quota ist das letzte Ereignis des Streams und wird nach end oder error gesendet:

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

Das gilt für Streams, die mit einem Serverschlüssel oder Legacy-Schlüssel gelesen werden. Bei einem Stream mit einem Sitzungstoken (aus einem veröffentlichbaren Schlüssel oder einer Besuchersitzung einer veröffentlichten Karte) enthält das Ereignis weder Tarifinformationen noch Zahlenwerte:

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

Feld	Serverschlüssel oder Legacy-Schlüssel	Sitzungstoken
type, meter, reset_at	Ja	Ja
product, period	Ja	Nein
tier	Ja	Nein
used, limit	Ja	Nein

Mit einem Serverschlüssel können Sie damit den Nutzungszähler ohne eine weitere Anfrage aktualisieren. Dabei gelten drei Einschränkungen:

• Das Feld remaining fehlt. Berechnen Sie limit - used.
• Das Ereignis wird nach Möglichkeit gesendet. Ein Stream kann ohne dieses Ereignis enden; warten Sie daher nicht darauf.
• Das Ereignis meldet den Verbrauch, warnt aber nicht. Es erscheint nie während einer laufenden Antwort und kann einen Stream nicht anhalten.

Um das Ereignis zu empfangen, lesen Sie weiter, bis der Antwort-Body geschlossen wird. Ein Client, der bei end aufhört, verpasst es.

Behandlung von 429 im Code

Lesen Sie vor Ihrer Entscheidung den Antwort-Body. Der Statuscode allein verrät nicht, ob ein erneuter Versuch sinnvoll ist.

Empfangene Antwort	Erneut versuchen?	Zeitpunkt
error: "quota_exceeded"	Nein	Nach reset_at, nach dem Hinzufügen von Credits oder einer Erhöhung der Schlüsselobergrenze. Dem Benutzer anzeigen, dass das Kontingent aufgebraucht ist.
error: "rate_limited", "org_overloaded", "b2b_overloaded", "limiter_unavailable"	Ja	Nach den in Retry-After angegebenen Sekunden mit zufälliger Verzögerung; höchstens einige Versuche.
error: "visitor_limit_reached"	Nein	Später; Besucher entsprechend informieren.
detail: "map_load_quota_exceeded"	Nein	Nach Zurücksetzung des Zeitraums oder dem Kauf eines Kartenladungspakets.
error: "tile_access_restricted"	Nein	Embed korrigieren: Tile-Produkt mit veröffentlichbarem Schlüssel auf einem zugelassenen Ursprung verwenden.

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;
}

Im Browser lässt sich der Header Retry-After aus Plattform-API-Antworten per JavaScript auslesen.

Verwandte Themen

• Fehler: alle Statuscodes und Fehlerkennungen.
• SSE-Protokollvertrag: Position des Ereignisses quota im Stream.
• Stream lesen: vollständige Clients mit Wiederholungs- und Timeout-Behandlung.
• API-Schlüssel erhalten: Leistungsumfang der einzelnen Tarife.