Fehler

Dies ist die vollständige Fehlerliste der Kaleidr-Plattform-API. Jeder Fehler hat einen HTTP-Status und einen Code: eine kurze, stabile Zeichenfolge, anhand derer Ihr Programm entscheiden kann. Der Status allein reicht nicht aus. 403 hat viele mögliche Ursachen, und 429 bedeutet sowohl „langsamer senden“ als auch „Kontingent aufgebraucht“.

Beginnen Sie mit den Antwortformaten, denn der Code steht nicht immer im selben Feld.

Antwortformate

Format	Beispiel	Verwendung
Eingepackter Code	{"detail": "origin_not_allowed"}	Fast alle Fehler 401, 403, 404, 413, 500 und 503, die 422-Anfragelimit-Codes sowie zwei 429-Fehler (map_load_quota_exceeded und ingest_rate_limited aus der Upload-API). Der Code ist die Zeichenfolge in detail.
Flaches Objekt	{"error": "rate_limited", "detail": "API key rate limit exceeded. Slow down."}	Alle übrigen 429-Fehler. Der Code steht in error; detail enthält einen für Menschen bestimmten Satz. Kontingentfehler enthalten weitere Felder.
Validierungsliste	{"detail": [{"loc": ["body", "product"], "msg": "…", "type": "…"}]}	422 bei fehlerhaftem Anfragekörper oder fehlerhafter Abfrage. detail ist ein Array mit einem Eintrag pro Problem.
Fehler bei 200	{"error": "Route planning failed."}	Nur POST /chat/control/route. Siehe unten.

Eine Funktion, die den Code aus allen Formaten ausliest:

async function kaleidrError(res) {
  const body = await res.json().catch(() => ({}));
  const code =
    typeof body.error === 'string' ? body.error :      // flat 429
    typeof body.detail === 'string' ? body.detail :    // wrapped code
    Array.isArray(body.detail) ? 'validation_error' :  // 422
    'unknown_error';
  return { status: res.status, code, body, retryAfter: Number(res.headers.get('retry-after')) || null };
}

Zwei Header sind wichtig: Retry-After bei 429-Antworten mit einer Wartezeit in Sekunden und, falls vorhanden, X-Request-Id zur Identifikation der Anfrage bei einer Supportanfrage.

Authentifizierung: 401

Die API akzeptiert die Anmeldedaten nicht.

Code	Wann er auftritt	Vorgehensweise
Invalid or missing API key	Es wurden keine Anmeldedaten gesendet, oder der Schlüssel ist unbekannt, widerrufen oder abgelaufen. Ebenfalls möglich: ein abgelaufenes Sitzungstoken; eine Sitzung, deren Schlüssel widerrufen oder ohne Übergangsfrist rotiert wurde; eine Sitzung, deren Ursprung oder Produkt aus dem Schlüssel entfernt wurde; eine vor einer Tarifherabstufung ausgestellte Sitzung; eine gesperrte Organisation oder eine Organisation ohne Tarif.	Prüfen Sie den Schlüssel und seinen Status unter kaleidr.com/api-keys. Tauschen Sie für eine Sitzung das Token erneut aus. Schlägt ein gültiger Schlüssel weiterhin fehl, versuchen Sie es kurz darauf erneut: Auch eine vorübergehende Plattformstörung kann diesen Fehler auslösen.
publishable_requires_session	Ein veröffentlichbarer Schlüssel (kld_pk_…) wurde an einen Laufzeit-Endpunkt gesendet.	Lassen Sie das SDK den Schlüssel im Browser austauschen oder rufen Sie zuerst POST /sdk/sessions auf. Verwenden Sie auf dem Backend einen Serverschlüssel.

Autorisierung: 403

Die API erkennt die Anmeldedaten, lehnt diese Anfrage aber ab.

Code	Wann er auftritt	Vorgehensweise
insufficient_scope	Der Schlüssel wurde ohne die Berechtigung erstellt, die dieser Endpunkt oder dieses Produkt benötigt.	Verwenden Sie einen Schlüssel mit der Berechtigung. Bestehende Schlüssel können keine zusätzlichen Berechtigungen erhalten.
tier_capability_not_allowed	Der Schlüssel verfügt über die Berechtigung oder das Produkt, aber der aktuelle Tarif Ihrer Organisation enthält es nicht. Dieser Fehler wird auch bei einer veröffentlichten Karte zurückgegeben, wenn der Tarif des Eigentümers keinen Chat enthält. Für vendor gilt dies nicht: Ein Schlüssel mit vendor wird in einem Tarif unter Enterprise nicht abgewiesen; seine Antworten werden jedoch ohne Ihre Daten erstellt.	Wechseln Sie den Tarif oder verwenden Sie ein im Tarif enthaltenes Produkt.
server_key_in_browser	Ein Serverschlüssel (kld_sk_…) wurde mit einem Origin-Header gesendet.	Verlegen Sie den Aufruf auf Ihr Backend. War der Schlüssel im Seitenquelltext sichtbar, rotieren Sie ihn.
session_origin_mismatch	Ein Sitzungstoken wurde von einem anderen Ursprung als dem Ausstellungsursprung verwendet, oder eine Sitzung einer veröffentlichten Karte wurde ohne Origin verwendet.	Tauschen Sie die Sitzung auf der Seite aus, auf der sie verwendet werden soll.
ip_not_allowed	Ein Server- oder Legacy-Schlüssel mit IP-Zulassungsliste wurde von einer nicht zugelassenen Adresse aufgerufen, oder die Absenderadresse konnte nicht festgestellt werden.	Senden Sie den Aufruf von einer zugelassenen Adresse oder ändern Sie allowed_ips des Schlüssels.
publishable_key_required	POST /sdk/sessions wurde mit einem Server- oder Legacy-Schlüssel aufgerufen.	Verwenden Sie einen veröffentlichbaren Schlüssel für den Austausch.
origin_required	Beim Sitzungsaustausch fehlte der Origin-Header.	Führen Sie den Austausch von einer Browserseite aus.
origin_not_allowed	Der Ursprung der Seite steht nicht in der Liste der erlaubten Ursprünge des Schlüssels oder nicht in den erlaubten Domains der veröffentlichten Karte.	Fügen Sie den genauen Ursprung dem Schlüssel oder die Domain der Karte hinzu.
product_not_allowed	Der Schlüssel ist auf bestimmte Produkte beschränkt, und diese Anfrage betrifft ein anderes Produkt. Beim Sitzungsaustausch: Das angeforderte product gehört nicht zu den erlaubten Produkten des veröffentlichbaren Schlüssels. Zur Laufzeit: Ein Server- oder Legacy-Schlüssel hat einen Endpunkt eines nicht zugelassenen Produkts aufgerufen, etwa wenn ein auf tile beschränkter Schlüssel /chat/* aufruft.	Ändern Sie allowed_products oder verwenden Sie einen anderen Schlüssel.
chat_disabled	Austausch für eine veröffentlichte Karte: Die Kaleidr AI der Karte aktiviert die angeforderte Funktion nicht.	Aktivieren Sie Control Tower oder Popup Window in der Kachel Kaleidr AI der Karte in Studio.
feature_not_granted	Eine für Popup-Chat geöffnete Sitzung einer veröffentlichten Karte wurde auf /chat/control/stream verwendet. Jede Funktion hat ihre eigene Sitzung.	Tauschen Sie eine Sitzung mit "feature": "control_tower" ein, die die Karte gewährt, solange Control Tower aktiviert ist.
owner_has_no_organization	Austausch für eine veröffentlichte Karte: Der Eigentümer der Karte hat keine Organisation, der die Kosten zugerechnet werden können.	Der Eigentümer muss eine Organisation erstellen oder ihr beitreten.

Nicht gefunden: 404

Code	Wann er auftritt	Vorgehensweise
not_found	Austausch für eine veröffentlichte Karte: Es existiert keine veröffentlichte Karte und kein Freigabelink mit dieser share_id.	Prüfen Sie die ID und ob die Karte veröffentlicht ist.
sessions_disabled	Der Sitzungsaustausch ist auf der Plattform abgeschaltet.	Das können Sie nicht selbst ändern. Kontaktieren Sie den Support.
Not Found	Der Pfad existiert nicht.	Vergleichen Sie die URL mit den Endpunkten, einschließlich des Präfixes /inference-api/b2b/v1.

Validierung: 422

Der Anfragekörper oder die Abfragezeichenfolge entspricht nicht den Vorgaben des Endpunkts. detail ist ein Array; in jedem Eintrag benennt loc das Feld und msg beschreibt den Fehler.

{
  "detail": [
    { "type": "missing", "loc": ["body", "product"], "msg": "Field required", "input": {} }
  ]
}

Korrigieren Sie die Anfrage und wiederholen Sie sie nicht unverändert. Zwei Streaming-Endpunkte, /chat/summary/stream und /chat/button/stream, antworten bei einem fehlerhaften Anfragekörper mit 500 statt 422, außer bei einem überlangen Feld (siehe unten).

Anfragelimits: 422 mit Fehlercode

Eine formal gültige Anfrage, die eine Größenbegrenzung überschreitet, erhält ebenfalls 422, allerdings im eingepackten Format: detail enthält den Code als Zeichenfolge und nicht als Array. Es wird nichts berechnet.

{ "detail": "conversation_too_long" }

Code	Endpunkt	Wann er auftritt	Vorgehensweise
too_many_messages	/chat/control/stream	messages enthält mehr als 400 Einträge.	Senden Sie nur die neuesten Gesprächsbeiträge.
message_too_long	/chat/control/stream	content einer einzelnen Nachricht ist länger als 64.000 Zeichen.	Kürzen Sie die Nachricht.
conversation_too_long	/chat/control/stream	Die Gesamtlänge von content aller Nachrichten überschreitet 200.000 Zeichen.	Entfernen Sie die ältesten Beiträge und senden Sie erneut.
invalid_session_id	/chat/control/stream	session_id ist länger als 128 Zeichen oder enthält andere Zeichen als Buchstaben, Ziffern, _, ., : oder -.	Verwenden Sie eine ID in diesem Format, z. B. eine UUID.
lang_too_long	/chat/control/stream	lang ist länger als 35 Zeichen.	Senden Sie ein BCP-47-Sprachkennzeichen wie pt-BR.
invalid_layout	/chat/control/stream	layout ist länger als 16 Zeichen.	Senden Sie guide, solange der Viewer sein Guide-Layout zeigt, oder lassen Sie das Feld weg.
field_too_long	/chat/summary/stream, /chat/button/stream	Ein Textfeld oder eine Liste überschreitet ihre jeweilige Begrenzung.	Kürzen Sie das Feld. Die Grenzen stehen unter Endpunkte.

Die Grenzen für den Chat-Stream stehen unter Endpunkte.

Anfrage zu groß: 413

Code	Wann er auftritt	Vorgehensweise
request_too_large	Der Anfragekörper überschreitet 2 MiB bzw. 5 MiB bei einem /design/*-Endpunkt. Der Körper ist {"detail": "request_too_large"}. Es wird nichts berechnet.	Senden Sie weniger Daten: Kürzen Sie den Gesprächsverlauf oder die Beispielzeilen einer Designanfrage. Senden Sie nicht denselben Anfragekörper erneut.
request_body_too_large	Eine Anfrage zur Schlüsselverwaltung oder zu Geschäftsdaten unter /shared-api überschreitet 1 MiB oder beim Upload-Aufruf POST /shared-api/datahub/ingests 32 MiB.	Senden Sie einen kleineren Anfragekörper. Für Uploads siehe Geschäftsdaten hochladen.

Eine Anfrage, deren deklarierte Größe weit über dem Limit eines Endpunkts liegt, kann bereits am Netzwerkrand abgewiesen werden, bevor sie die API erreicht. Diese Antwort enthält keinen Kaleidr-JSON-Körper und damit keinen auslesbaren Code: Senden Sie weniger Daten.

Eine wegen ihrer Größe abgewiesene Anfrage wird wie jede vor der Verarbeitung abgelehnte Anfrage nicht berechnet und belegt anschließend weder KI-Guthaben noch einen gleichzeitigen Anfrageplatz.

Kontingent- und Ratenlimits: 429

Lesen Sie den Antwortkörper, bevor Sie entscheiden, ob Sie den Aufruf wiederholen.

Code	Feld	Retry-After	Wann tritt dies auf?	Was ist zu tun?
quota_exceeded	error	Sekunden bis reset_at	Das KI-Guthaben Ihrer Organisation reicht für die Anfrage nicht aus oder das monatliche Limit des Schlüssels würde überschritten. Wird auch vom Aufruf für einen Zuordnungsvorschlag der Upload-API zurückgegeben.	Nicht erneut versuchen. Bis reset_at warten, Guthaben hinzufügen oder das Schlüssellimit anheben.
rate_limited	error	5	Das Anfragelimit des Schlüssels pro Minute ist erreicht. Ebenfalls bei zu vielen Sitzungs-Austauschen für einen Schlüssel, eine veröffentlichte Karte oder eine einzelne Adresse.	Die in Retry-After angegebene Anzahl Sekunden warten und dann mit zufälligem Zeitversatz erneut versuchen.
org_overloaded	error	5	Ihre Organisation führt bereits zu viele Anfragen gleichzeitig aus.	Warten, bis eine laufende Anfrage beendet ist, und dann erneut versuchen. Nicht mehr benötigte Streams schließen.
b2b_overloaded	error	5	Die API hat ihre Kapazitätsgrenze für alle Aufrufenden erreicht.	Die in Retry-After angegebene Anzahl Sekunden warten und dann mit exponentiell steigender Wartezeit erneut versuchen.
limiter_unavailable	error	5	Der Ratenbegrenzer konnte nicht antworten.	In Kürze erneut versuchen. Das Problem hängt nicht mit Ihrer Anfragerate zusammen.
visitor_limit_reached	error	5	Eine Person hat im Chat einer veröffentlichten Karte das Minuten- oder Tageslimit überschritten.	Dem Besucher mitteilen, dass er es später erneut versuchen soll.
map_load_quota_exceeded	detail	keiner	POST /sdk/sessions für tile: Das Kontingent der Kartenaufrufe Ihrer Organisation ist aufgebraucht.	Nicht erneut versuchen. Auf das Zurücksetzen des Zeitraums warten oder ein Kartenaufrufpaket hinzufügen.

Der Antwortkörper von quota_exceeded enthält die Zahlen:

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

Diesen Antwortkörper erhält ein Serverschlüssel. Eine Anfrage mit einem Sitzungstoken (aus einem veröffentlichbaren Schlüssel ausgetauscht oder aus der Besuchersitzung einer veröffentlichten Karte) erhält einen kürzeren Körper, der weder den Tarif noch die Nutzung der Organisation offenlegt:

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

Die einzelnen Felder, die Variante mit Limit pro Schlüssel und Beispielcode zur Behandlung sind unter Kontingente und Ratenbegrenzungen beschrieben.

Serverfehler: 5xx

Status	Code	Wann er auftritt	Vorgehensweise
500	An internal error occurred. Please try again.	Ein unerwarteter Fehler.	Versuchen Sie es nach kurzer Wartezeit einmal erneut.
500	map_design_analyze_failed	POST /design/analyze konnte die Tabelle nicht analysieren. Keine Berechnung.	Prüfen Sie die Spalten und Beispielzeilen der Tabelle und versuchen Sie es erneut.
500	Summary stream error	POST /chat/summary/stream konnte nicht starten: ein nicht lesbarer Anfragekörper oder eine Gebäudeanfrage ohne address. Ein überlanges Feld ergibt stattdessen 422 field_too_long.	Korrigieren Sie den Anfragekörper.
500	Button chat stream error	POST /chat/button/stream konnte nicht starten: ein nicht lesbarer Anfragekörper oder einer ohne query. Ein überlanges Feld ergibt stattdessen 422 field_too_long.	Korrigieren Sie den Anfragekörper.
503	sessions_not_configured	Der Sitzungsaustausch ist wegen einer Plattformstörung nicht verfügbar.	Versuchen Sie es erneut; kontaktieren Sie den Support, falls der Fehler bestehen bleibt.
503	share_grant_unavailable	Austausch für eine veröffentlichte Karte: Die Einstellungen der Karte konnten nicht gelesen werden.	Versuchen Sie es in Kürze erneut.

Fehler mit Status 200

POST /chat/control/route gibt 200 zurück, wenn keine Route geplant werden kann:

{ "error": "Route planning failed." }

Die Antwort enthält error, aber keine action. Ein Client, der nur den Status prüft, wertet dies als Erfolg und scheitert anschließend beim Lesen von action. Prüfen Sie immer, ob der Antwortkörper error enthält. Der Text ist zur direkten Anzeige für Benutzer formuliert. Details: Wegbeschreibungen.

GET /retrieval/geocode/forward verhält sich ähnlich: Eine intern fehlgeschlagene Suche gibt 200 mit einer leeren results-Liste zurück, genau wie eine Suche ohne Treffer.

Fehler im Stream

Alles bisher Beschriebene gilt vor Beginn eines Streams: Eine abgelehnte Streaming-Anfrage ist ein gewöhnlicher HTTP-Fehler. Sobald die Antwort 200 ist und Frames übertragen werden, erscheint ein Fehler als error-Ereignis:

event: error
data: {"type": "error", "code": "upstream_stall", "message": "The AI service stopped responding. Please try again.", "partial_text": "The Louvre sits"}

Stream	code	Wann er auftritt	Vorgehensweise
/chat/control/stream	upstream_stall	Die Antwort machte keine Fortschritte mehr oder der Stream erreichte seine maximale Dauer von ungefähr 10 Minuten.	Bieten Sie einen erneuten Versuch an. Behalten Sie partial_text, falls er hilfreich ist.
/chat/control/stream	fehlt	Jeder andere Fehler während der Antwortgenerierung.	Zeigen Sie message an. Ein neuer Versuch kann gelingen.
/chat/summary/stream	fehlt	Die Zusammenfassung schlug fehl.	Zeigen Sie message an oder verzichten Sie auf die Zusammenfassung.
/spot/overview/stream	fehlt	Der Überblick schlug fehl oder die angegebene ref kann nicht beschrieben werden. In letzterem Fall enthält das Ereignis die ref: eine poi:- oder region:-Referenz, die nicht am Punkt liegt, place: ohne hint.name oder ein Gebäude bzw. eine Adresse, die die API nicht beschreibt.	Zeigen Sie keinen Überblick. Wiederholen Sie ein Ereignis, das eine ref enthält, nicht.
/chat/button/stream	keiner	Dieser Stream hat kein error-Ereignis. Ein Fehler schließt die Verbindung ohne end.	Werten Sie einen Stream, der ohne end schließt, als fehlgeschlagen.

Regeln für jeden Stream:

• Ein error-Ereignis ersetzt end. Danach kann nur noch ein optionales quota-Ereignis folgen.
• Eine Verbindung, die ohne end und ohne error schließt, ist fehlgeschlagen.
• Das quota-Ereignis ist kein Fehler. Es ist ein Nutzungsbericht, der nach end oder error gesendet wird. Bei einem mit Sitzungstoken gelesenen Stream enthält er nur type, meter und reset_at.
• Ein unbekannter Ereignisname ist kein Fehler. Ignorieren Sie ihn.

Ein fehlgeschlagener oder vorzeitig geschlossener Stream wird trotzdem berechnet. Bei /chat/control/stream ist die Berechnung niemals geringer als die geschätzte Größe des gesendeten Gesprächs. Sie kann daher höher sein als die anfänglich reservierten Guthabenpunkte. Siehe Abrechnung eines Streams. Ein erneuter Versuch ist eine neue, separat berechnete Anfrage.

Fehler, die der Browser verbirgt

Wenn der Ursprung oder die Anmeldedaten abgewiesen werden, enthält die Antwort keinen CORS-Header. Der Browser hält Status und Antwortkörper vor Ihrem Code zurück. Die Seite sieht in der Konsole einen CORS-Fehler und einen abgewiesenen fetch; das SDK protokolliert einen Fehler mit [kaleidr:<product>].

Um den tatsächlichen Code zu lesen, öffnen Sie den Netzwerk-Tab und wählen Sie die fehlgeschlagene Anfrage. Häufig sind origin_not_allowed, Invalid or missing API key und server_key_in_browser. Siehe CORS und erlaubte Ursprünge.

Eine 4xx-Antwort ganz ohne Kaleidr-JSON-Körper stammt vom Netzwerkrand vor der API. Ursache ist entweder eine Ratenbegrenzung (später mit Wartezeit erneut versuchen) oder eine Anfrage, deren deklarierte Größe weit über jedem Endpunktlimit liegt (weniger senden; dieselbe Anfrage erneut zu senden ergibt denselben Fehler).

Tile-Host

Anfragen an tile.kaleidr.com, die nicht von einem Kaleidr-Embed mit gültigem veröffentlichbarem Schlüssel und zugelassenem Ursprung stammen, erhalten:

Status	Code	Retry-After	Vorgehensweise
429	tile_access_restricted (in error, mit message und docs)	3600	Verwenden Sie das Tile-Produkt mit einem veröffentlichbaren Schlüssel und tragen Sie den Ursprung der Seite in dessen Zulassungsliste ein, falls eine solche Liste vorhanden ist.

Schlüsselverwaltung

Fehler von https://api.kaleidr.com/shared-api/api-keys, das von der Seite API Keys genutzt wird und mit dem Zugriffstoken Ihres Kontos aufgerufen werden kann. Alle verwenden das eingepackte Format.

Status	Code	Wann er auftritt	Vorgehensweise
401	verschieden	Kein gültiges Konto-Zugriffstoken. Ein Plattformschlüssel wird hier nicht akzeptiert.	Melden Sie sich erneut an.
403	org_admin_required	Ihr Konto ist weder Eigentümer noch Administrator der Organisation.	Fragen Sie einen Eigentümer oder Administrator.
403	plan_required	Die Organisation hat keinen Tarif.	Wählen Sie unter kaleidr.com/billing einen Tarif.
403	free_plan_publishable_only	Im Free-Tarif wurde ein Serverschlüssel angefordert. Auch beim Rotieren eines Server- oder Legacy-Schlüssels unter Free.	Erstellen Sie einen veröffentlichbaren Schlüssel oder wechseln Sie zu Pro.
403	tier_capability_not_allowed	Beim Erstellen eines Schlüssels nennen scopes oder allowed_products eine Berechtigung bzw. ein Produkt, das Ihr Tarif nicht zulässt. Praktisch betrifft dies vendor unter Free oder Pro: Die Anfrage wird unabhängig davon abgewiesen, ob vendor_acknowledged mitgesendet wird; es wird kein Schlüssel erstellt. Beim Bearbeiten nennt allowed_products ein nicht enthaltenes Produkt oder wird im Free-Tarif als leere Liste gesetzt.	vendor erfordert Enterprise. Geben Sie andernfalls nur im Tarif enthaltene Berechtigungen und Produkte an.
404	key_not_found	In dieser Organisation existiert kein Schlüssel mit dieser ID. Bearbeiten und Widerrufen finden Schlüssel jeden Status; der erneute Widerruf eines bereits widerrufenen Schlüssels gibt daher 200 zurück. Rotieren erfordert einen aktiven Schlüssel und liefert diesen Code bei widerrufenen Schlüsseln.	Prüfen Sie die ID. Bei einer Rotation kann der Schlüssel bereits widerrufen sein.
409	key_limit_reached	Die Organisation hat die Zahl aktiver Schlüssel ihres Tarifs erreicht (Free 2, Pro 10, Enterprise 25).	Widerrufen Sie einen Schlüssel oder rotieren Sie einen vorhandenen, statt einen neuen zu erstellen.
409	key_already_rotated	Der Schlüssel wurde bereits rotiert, unabhängig davon, ob seine Übergangsfrist abgelaufen ist. Er kann nicht nochmals rotiert werden; auch eine Bearbeitung, die expires_at löscht oder auf einen Zeitpunkt nach Ende der Übergangsfrist setzt, wird verweigert. Ein früheres expires_at und andere Schlüsselfelder bleiben bearbeitbar.	Verwenden Sie den Ersatzschlüssel.
409	key_expired	Ein nie rotierter Schlüssel ist abgelaufen, und die Bearbeitung enthält expires_at. Ein abgelaufener Schlüssel kann kein neues Ablaufdatum erhalten; seine anderen Felder können bearbeitet werden.	Erstellen Sie einen neuen Schlüssel.
413	request_body_too_large	Der Anfragekörper ist größer als 1 MiB.	Senden Sie einen kleineren Körper.
422	unknown_scope	scopes enthält einen anderen Wert als ai, maps, design, vendor.	Korrigieren Sie die Liste.
422	unknown_product	allowed_products enthält einen anderen Wert als chat, editor, viewer, tile.	Korrigieren Sie die Liste.
422	vendor_scope_requires_acknowledgement	Unter Enterprise wurde ein veröffentlichbarer Schlüssel mit vendor ohne vendor_acknowledged: true angefordert. Unter Free und Pro ergibt dieselbe Anfrage 403 tier_capability_not_allowed.	Lesen Sie die Berechtigung vendor und senden Sie dann das Feld.
422	no_fields_to_update	Bearbeitungsanfrage ohne bearbeitbares Feld.	Senden Sie mindestens ein Feld.
422	Validierungsliste	Fehlerhafter Ursprung, IP-Eintrag, Ablaufzeitpunkt in der Vergangenheit oder Name.	Korrigieren Sie das unter loc genannte Feld.
500	insert_failed, session_unavailable	Eine Plattformstörung.	Versuchen Sie es erneut.
503	api_key_pepper_not_configured	Wegen einer Plattformstörung können keine Schlüssel erstellt werden.	Versuchen Sie es erneut; kontaktieren Sie bei anhaltendem Fehler den Support.

Hochladen von Geschäftsdaten

Fehler der Upload-Routen unter https://api.kaleidr.com/shared-api/datahub und des Aufrufs für Zuordnungsvorschläge. Die vollständige Liste einschließlich Datei- und Feldlimits für die einzelnen 422-Fehler steht unter Geschäftsdaten hochladen. Hier folgen die Fehler, die eine Anfrage vor dem Einlesen einer Datei abweisen, sowie die Fehler beim Zurücknehmen einer Veröffentlichung und beim Löschen eines Releases:

Status	Code	Wann er auftritt	Vorgehensweise
403	org_admin_required	Das Konto ist weder Eigentümer noch Administrator der Organisation. Auch der Aufruf für Zuordnungsvorschläge gibt diesen Fehler zurück.	Fragen Sie einen Eigentümer oder Administrator.
403	vendor_data_not_on_plan	Der Tarif der Organisation erlaubt keinen Upload von Geschäftsdaten. Diese Funktion ist nur in Enterprise enthalten. Der Fehler tritt bei Upload, Veröffentlichung, erneuter Verarbeitung und Zuordnungsvorschlägen auf, niemals beim Lesen, Zurücknehmen oder Löschen.	Wechseln Sie zu Enterprise. GET /shared-api/datahub/limits gibt in jedem Tarif ohne Abweisung an, ob die Organisation hochladen darf. Unter Free und Pro können Sie stattdessen Daten zu einer Karte in Kaleidr Studio hinzufügen: siehe Datensätze auf einer Karte.
404	release_not_found	Beim Zurücknehmen oder Löschen existiert kein Release mit dieser ID in der Organisation, auch wenn es bereits vollständig gelöscht wurde.	Behandeln Sie einen Löschvorgang in diesem Fall als bereits abgeschlossen.
409	org_ingest_in_progress	Ein anderer Upload der Organisation wird noch verarbeitet. Wird von Upload-, Veröffentlichungs- und Neuverarbeitungsaufrufen zurückgegeben.	Warten Sie auf das Ende und senden Sie dann erneut.
409	release_not_published	Das Zurücknehmen der Veröffentlichung wurde für einen Entwurf oder ein fehlgeschlagenes Release aufgerufen.	Es gibt nichts zurückzunehmen. Löschen Sie es stattdessen.
409	release_is_published	Das Löschen wurde für das aktuell veröffentlichte Release aufgerufen.	Nehmen Sie die Veröffentlichung zurück und löschen Sie dann.
413	request_body_too_large	Die Upload-Anfrage ist größer als 32 MiB.	Senden Sie eine kleinere Datei. Für die Datei selbst gilt die Größenbegrenzung Ihrer Organisation.
422	{ "errors": [ … ] } in detail	Die Datei überschreitet eine Zeilen- oder Größenbegrenzung, ein Feld eines JSON-Bundles überschreitet seine Längenbegrenzung oder das JSON ist zu tief verschachtelt. Bei einem vertraglich festgelegten Limit werden der Grenzwert und der Tarif im Grund genannt.	Lesen Sie alle Gründe und korrigieren Sie die Datei.
429	ingest_rate_limited	Die Organisation hat in der letzten Stunde 30 Uploads gestartet.	Warten Sie und senden Sie erneut.
429	ein Satz in detail	Das Konto hat in der letzten Stunde 30 Zuordnungsvorschläge erstellt. Der Antwortkörper hat kein Feld error.	Warten Sie und senden Sie erneut.
429	quota_exceeded in error	Zuordnungsvorschlag: Das KI-Guthaben der Organisation ist aufgebraucht. Der Körper entspricht der üblichen Kontingentantwort.	Warten Sie bis reset_at, kaufen Sie Guthaben hinzu oder erstellen Sie die Zuordnung manuell.

Datensatz-Uploads in Kaleidr Studio

Dieser Abschnitt gehört nicht zur Plattform-API mit Schlüsselauthentifizierung. Er beschreibt die Antwort, die Kaleidr Studio erhält, wenn ein angemeldeter Benutzer im Datenbereich einer Karte einen Datensatz hinzufügt und der Upload wegen seiner Größe verweigert wird. Es ist kein API-Schlüssel beteiligt. Es gibt zwei Arten der Ablehnung mit unterschiedlicher Bedeutung:

Status	Code	Wann er auftritt	Vorgehensweise
402	quota_exceeded	Ein neuer Datensatz-Upload überschreitet eine der Tarifgrenzen der Organisation: Zeilen in einem Datensatz, Dateigröße oder Gesamtzahl der Zeilen in allen Datensätzen. limit_key nennt die verletzte Grenze. Bereits gespeicherte Daten bleiben erhalten. Studio zeigt die Nachricht mit einem Upgrade-Link.	Laden Sie eine kleinere Datei hoch oder entfernen Sie nicht mehr benötigte Datensätze. Wechseln Sie unter Free zu Pro. Unter Pro oder Enterprise können Sie Kaleidr kontaktieren, um das Organisationsgesamtlimit zu erhöhen; das Zeilen- und Dateigrößenlimit pro Datensatz kann nicht über die Obergrenzen der nächsten Zeile angehoben werden.
400	VALIDATION_ERROR	Datei oder Datensatz überschreiten eine Obergrenze, die für jeden Tarif gilt: Datei größer als 64 MiB, Datensatz mit mehr als 100.000 Zeilen, Geodatei mit mehr als 50.000 Features oder Bildoverlay größer als 16 MiB. Der Code steht in error. Ein Tarifwechsel erlaubt diesen Upload nicht.	Teilen Sie die Datei in kleinere Teile. Wiederholen Sie denselben Upload nicht und bieten Sie kein Upgrade an.

Welche Antwort Sie erhalten, hängt von der Größe ab und nicht nur vom Tarif. Die allgemeine Obergrenze wird zuerst geprüft: Eine Datei über 64 MiB oder ein Datensatz über 100.000 Zeilen liefert unter Free, Pro und Enterprise gleichermaßen 400. Der Status 402 gilt für einen Upload unterhalb der allgemeinen Obergrenze, aber oberhalb des eigenen Organisationslimits: etwa eine 40-MiB-Datei unter Free mit einer Grenze von 32 MiB.

402 quota_exceeded

Der Antwortkörper ist ein Problem-Details-Objekt mit den zusätzlichen Studio-Feldern error und message. Der Code steht sowohl in error als auch in code, der Text sowohl in message als auch in detail:

{
  "error": "quota_exceeded",
  "message": "Your plan allows 250,000 rows across all of your organization's datasets. Delete a dataset or upgrade to add more.",
  "type": "https://errors.kaleidr.com/datasets/quota_exceeded",
  "title": "Quota Exceeded",
  "status": 402,
  "detail": "Your plan allows 250,000 rows across all of your organization's datasets. Delete a dataset or upgrade to add more.",
  "code": "quota_exceeded",
  "limit_key": "studio.data.rows.max",
  "limit": 250000,
  "used": 248500,
  "tier": "free",
  "upgrade_url": "https://kaleidr.com/pricing"
}

Feld	Bedeutung
error, code	Immer quota_exceeded. Derselbe Wert zweimal.
message, detail	Derselbe Satz zweimal. Er beschreibt das Limit verständlich und ist zur Anzeige für Benutzer bestimmt.
type	Immer https://errors.kaleidr.com/datasets/quota_exceeded.
title	Immer Quota Exceeded.
status	Immer 402.
limit_key	Welches Limit den Upload verweigert hat. Siehe nächste Tabelle.
limit	Das Organisationslimit in der zugehörigen Maßeinheit.
used	Beim Gesamtlimit die bereits von der Organisation gespeicherten Zeilen. Bei den anderen beiden die Zeilen oder MiB dieses Uploads.
tier	Der Organisationstarif: free, pro oder enterprise. Kann der Tarif nicht gelesen werden, lautet der Wert unknown und die Free-Grenzen gelten.
upgrade_url	Adresse für den Tarifwechsel.

limit_key	Limit	Einheit von limit und used	Der Satz
studio.dataset.rows.max	Zeilen in einem Datensatz	Zeilen	„Ihr Tarif erlaubt 50.000 Zeilen pro Datensatz. Laden Sie eine kleinere Datei hoch oder wechseln Sie den Tarif.“
studio.dataset.file.mb	Größe einer hochgeladenen Datei	MiB	„Ihr Tarif erlaubt Dateien bis 32 MB. Laden Sie eine kleinere Datei hoch oder wechseln Sie den Tarif.“
studio.data.rows.max	Zeilen aller Organisationsdatensätze	Zeilen	„Ihr Tarif erlaubt insgesamt 250.000 Zeilen in allen Datensätzen Ihrer Organisation. Löschen Sie einen Datensatz oder wechseln Sie den Tarif, um weitere hinzuzufügen.“

Die Zahlen in diesen Sätzen sind die Free-Grenzen; der tatsächlich empfangene Satz enthält die Grenzwerte Ihrer Organisation. Zeigen Sie den Satz an und verzweigen Sie im Programm anhand von code und limit_key. Dieser 402-Fehler unterscheidet sich vom 429-Fehler quota_exceeded der Plattform-API, der sich auf KI-Guthaben bezieht.

400 VALIDATION_ERROR

Der Antwortkörper hat zwei Felder und keine weiteren Problem-Details-Einträge:

{
  "error": "VALIDATION_ERROR",
  "message": "File is larger than 64 MB."
}

Grund der Ablehnung	message
Datei größer als 64 MiB	„Datei ist größer als 64 MB.“
Datensatz mit mehr als 100.000 Zeilen	„Maximal 100000 Datensätze pro Datensatz“
Geodatei mit mehr als 50.000 Features	„<filename> enthält mehr als 50000 Features. Teilen oder vereinfachen Sie die Geometrie vor dem Hochladen.“
Bildoverlay größer als 16 MiB	„Overlay-Bild ist größer als 16 MB.“

Derselbe Status und Code werden auch bei anderen Problemen mit einer hochgeladenen Datei zurückgegeben, etwa bei einem von Studio nicht lesbaren Dateityp oder einer Datei ohne verwendbare Zeilen; message nennt den Grund. Behandeln Sie jede 400-Antwort eines Uploads als „Diese Datei kann in dieser Form nicht hinzugefügt werden“ und zeigen Sie message an.

Verwandte Themen

• Authentifizierung und Berechtigungen: Anmeldedaten und Sitzungsaustausch.
• Kontingente und Ratenbegrenzungen: die 429-Antwortkörper im Detail.
• SSE-Protokollvertrag: Ereignisse eines Streams.
• Fehlerbehebung: Probleme nach Symptom.