Fehler

Platform-API-Fehler verwenden standardmäßige HTTP-Statuscodes. Fast jeder Fehler enthält einen stabilen Subcode-String, nach dem Clients verzweigen sollten — Statuscodes allein sind mehrdeutig (403 umfasst Scope, Produkt, Origin, IP und Schlüsseltyp).

Envelope

Die meisten Fehler geben einen FastAPI-ähnlichen Detail-Wrapper zurück:

{ "detail": "<subcode>" }

Strukturierte 429-Payloads (map_load_quota_exceeded, b2b_overloaded, org_overloaded, tile_access_restricted) sind flache Objekte auf der obersten Ebene — ohne detail-Wrapper:

{ "error": "map_load_quota_exceeded", "meter": "map_loads", "limit": 50000, "used": 50000 }

429-Fehler mit String-Detail (Map-Load-Hard-Stops) behalten den Wrapper:

{ "detail": "map_load_hard_stop" }

Einige nicht-streamenden Endpoints melden Fehler als HTTP 200 mit einem error- Key — insbesondere POST /chat/control/route. Wer nur nach Status verzweigt, behandelt diese als Erfolg. Lies immer den Body.

Tabelle

Status	Subcode	Bedeutung	Maßnahme
401	(no detail)	Fehlender / ungültiger / widerrufener / abgelaufener Schlüssel	Prüfe den Schlüsselwert und ob er nicht widerrufen wurde. Viewer benötigt keinen Schlüssel.
401	publishable_requires_session	Ein Publishable Key (kld_pk_…) wurde als direkter Bearer gesendet	Verwende ihn über das SDK, das ihn gegen eine Session austauscht.
403	insufficient_scope	Gültiger Schlüssel, aber der Scope der Route fehlt	Erstelle / erstelle erneut einen Schlüssel mit dem richtigen Scope (ai / maps / design).
403	tier_capability_not_allowed	Der gespeicherte Schlüssel hatte die Capability, aber der aktuelle Tier der Organisation erlaubt sie nicht mehr (typischerweise Pro→Free-Downgrade)	Upgrade den Plan oder verwende ein Produkt, das der aktuelle Tier erlaubt.
403	origin_required	Ein Publishable Key wurde ohne Browser-Origin verwendet (z. B. serverseitig)	Publishable Keys sind nur für den Browser.
403	session_origin_mismatch	Der Request-Origin steht nicht in der Allowlist des Schlüssels	Aktualisiere die Allowed Origins des Schlüssels (siehe API-Schlüssel erhalten).
403	product_not_allowed	Der Schlüssel ist für dieses Produkt nicht zugelassen	Erstelle einen Schlüssel mit Produktzulassung (oder verwende Viewer, der schlüssellos ist).
403	server_key_in_browser	Ein Server Key (kld_sk_…) wurde im Browser verwendet	Server Keys sind nur serverseitig; außerdem durch CORS blockiert.
403	ip_not_allowed	Ein Server Key wurde von einer IP außerhalb seiner Allowlist verwendet	Aktualisiere die IP-Allowlist des Schlüssels oder rufe von einer erlaubten Adresse auf.
403	publishable_key_required	Der SDK-Session-Austausch wurde mit etwas anderem als einem Publishable Key versucht	Verwende beim Session-Exchange-Schritt einen kld_pk_…-Schlüssel.
403	sessions_disabled	Session-Ausgabe ist für dieses Deployment deaktiviert	Support kontaktieren — dies ist ein Betriebszustand, keine Kundeneinstellung.
403	sessions_not_configured	Session-Infrastruktur ist nicht konfiguriert	Support kontaktieren.
422	(various)	Fehlerhafter Request-Body	Korrigiere die Payload (siehe Endpoints). Beim Mint bedeuten unknown_scope / unknown_product einen unbekannten Wert; publishable_live_requires_origins bedeutet, dass ein Live-Publishable-Key ohne Allowed Origins erstellt wurde.
429	(flat) map_load_quota_exceeded	Das monatliche Map-Loads-Kontingent der Organisation ist aufgebraucht	Upgrade oder reduziere Basemap-Ladevorgänge.
429	map_load_hard_stop	Bezahlte Organisation liegt beim Map-Loads-Kontingent 5× darüber	Die Auslieferung stoppt hier; der Soft-Bereich oberhalb des Kontingents funktioniert weiterhin.
429	(flat) tile_access_restricted	Tile-Anfrage abgelehnt (meist Origin-Allowlist-Fehler). Enthält Retry-After: 3600	Füge den Seiten-Origin zur Allowlist des Schlüssels hinzu; versuche es nach dem Header-Intervall erneut.
429	(flat) b2b_overloaded	Globales Request-Shedding ist aktiv	Zurückfahren und mit Jitter erneut versuchen.
429	(flat) org_overloaded	Request-Shedding pro Organisation	Zurückfahren und erneut versuchen.
429	limiter_unavailable	Rate Limiter ist vorübergehend nicht erreichbar	Als temporär behandeln; erneut versuchen.
429	rate_limited	Derzeit zu viele Anfragen	Retry-After beachten.
503	(no detail)	Key-Service vorübergehend nicht verfügbar	Temporär — in Kürze erneut versuchen.

Schlüsselverwaltung

Fehler von POST/PATCH/DELETE /shared-api/api-keys/* (Cognito org-admin JWT, kein Plattformschlüssel):

Status	Subcode	Bedeutung
403	free_plan_publishable_only	Organisationen im Free-Tier können nur Publishable Keys erstellen.
403	plan_required	Die Organisation hat keine erkannte API-Plan-Zeile.
403	tier_capability_not_allowed	Ein PATCH versuchte, einen Schlüssel über die Zulassung des aktuellen Tiers hinaus zu erweitern.
403	vendor_scope_requires_acknowledgement	Der vendor-Scope erfordert eine ausdrückliche Bestätigung pro Schlüssel.
409	key_limit_reached	Die Organisation hat das planabhängige Schlüssel-Limit pro Organisation erreicht.

Siehe API-Schlüssel erhalten für den vollständigen Mint-Ablauf und den PATCH- Update-Pfad.

Streaming-Fehler

In einem SSE-Stream kommt ein endgültiger Fehler als error-Event statt als HTTP-Status an (die Response wurde bereits mit 200 gestartet):

event: error
data: { "type":"error", "message":"…", "code":"…", "partial_text":"…" }

Behandle ein error-Event als Ende dieses Streams. Ein quota-Event während des Streams ist kein Fehler — es ist der Zähler, der dir mitteilt, wie viel Budget noch übrig ist. Clients müssen unbekannte Event-Namen ignorieren — neue Events können innerhalb des stabilen Contracts ohne Versionssprung hinzugefügt werden.

CORS "blockiert" im Browser

Wenn der Browser bei einer echten Anfrage einen CORS-Block meldet, steht der Request-Origin nicht in der Allowlist des Schlüssels — es ist kein Auth-Fehler. Siehe CORS & allowed origins.