Fehlercodes der Booking API

Diese Referenz listet die Fehler auf, die Ihrer Anwendung beim Aufbau eines Warenkorbs und beim Checkout mit der Booking API am häufigsten begegnen, und wie Sie jeweils reagieren.

Wie Fehler gemeldet werden

Die Booking API meldet Probleme an zwei Stellen.

Stelle	Wann	Vorgehen
`errors` auf oberster Ebene der Antwort	Die Validierung ist vor der Ausführung fehlgeschlagen, oder bei einem Feld ist während der Ausführung ein Fehler aufgetreten.	Korrigieren Sie die Anfrage. Senden Sie bei einem Token der falschen Art das richtige Warenkorb- oder Rechnungs-Token. Beachten Sie die folgenden Hinweise zu Token-Fehlern.
`errors` im Mutationsergebnis	Die Operation wurde ausgeführt und abgelehnt, zum Beispiel weil ein Zeitfenster ausgebucht ist.	Entscheiden Sie anhand von `message`, zeigen Sie `messageTranslated` an und lassen Sie den Kunden die Eingabe korrigieren.

Fehler bei der Schemavalidierung und bei der Typumwandlung von Variablen verhindern die Ausführung. Während der Ausführung auftretende Fehler können zusammen mit teilweise gefüllten data zurückgegeben werden: Ein anderes Mutationsfeld kann bereits erfolgreich ausgeführt worden sein und Änderungen gespeichert haben. Fehler auf oberster Ebene beweisen nicht, dass kein Schreibvorgang stattgefunden hat. Prüfen Sie die zurückgegebenen data und den path jedes Fehlers und lesen Sie den Warenkorb sowie eine eventuell vorhandene Rechnung, bevor Sie Schreibvorgänge wiederholen.

Jeder Mutationsfehler hat drei Felder:

Feld	Inhalt
`key`	Die Eingabe, auf die sich der Fehler bezieht, als Pfad wie `requestItems.0.pricings.0.quantity`. Indizes beginnen bei 0.
`message`	Ein maschinenlesbarer Code wie `invalid`. Entscheiden Sie anhand dieses Codes, wie Ihre Anwendung reagiert.
`messageTranslated`	Text für Kunden in der Sprache des `Accept-Language`-Headers. Für Codes ohne eigenen Text ist er allgemein, etwa „Ungültiger Wert“; dafür können Sie einen eigenen Text anzeigen.

Treffen Sie keine Entscheidungen anhand von messageTranslated: Der Wortlaut kann sich ändern. Die Listen messages und messagesTranslated sind veraltet.

Fehler auf oberster Ebene zu ungültigen Variablen wiederholen den gesendeten Wert in extensions.value. Das kann ein Warenkorb- oder Rechnungs-Token sein. Protokollieren oder übermitteln Sie Fehlerantworten deshalb nicht ungefiltert.

Fehler auf oberster Ebene

Meldung enthält	Ursache	Vorgehen
`Not authorized`	Das Warenkorb- oder Rechnungs-Token ist ungültig oder abgelaufen.	Legen Sie bei einem unbrauchbaren oder abgelaufenen Warenkorb-Token einen neuen Warenkorb an. Verwenden Sie bei einer Rechnung ein gültiges Token für dieselbe Rechnung.
`expected: Request`	Es wurde ein Token der falschen Art gesendet, zum Beispiel ein Rechnungs-Token als Warenkorb-Token.	Senden Sie das Warenkorb-Token.
`was provided invalid value`	Eine Variable passt nicht zu ihrem Eingabetyp.	Prüfen Sie die Variablen anhand der Referenz.
`was provided invalid value`, mit `single top level field` in `extensions.problems`	Die Anfrage verwendet ein Warenkorb- oder Rechnungs-Token und fragt mehr als ein Feld auf oberster Ebene ab.	Senden Sie jedes Feld auf oberster Ebene in einer eigenen Anfrage.
`doesn't exist on type`	Die Abfrage wählt ein Feld aus, das die Booking API nicht anbietet.	Entfernen Sie das Feld oder prüfen Sie die Referenz.

Positionen hinzufügen und ändern

Diese Fehler kommen von requestItemCreate, requestItemUpdate und requestItemDiscard sowie von Positionen, die mit requestUpdate gesendet werden. Die Schlüssel beginnen auch dann mit requestItems.0, wenn Sie nur eine Position hinzufügen.

Schlüssel	Code	Ursache	Vorgehen
`requestItems.0.pricings.0.quantity`	`sum_less_than_or_equal_to`	Für die gewünschte Menge sind nicht genug Plätze frei.	Verringern Sie die Menge oder lassen Sie den Kunden einen anderen Termin oder ein anderes Zeitfenster wählen.
`requestItems.0.pricings.0.quantity`	`greater_than_or_equal_to`, `less_than_or_equal_to`	Die Menge liegt außerhalb der Mindest- oder Höchstpersonenzahl der Preiskategorie.	Passen Sie die Menge an.
`requestItems.0.offerableSpan`	`required`, `invalid`	Einer Position für eine Eventvorlage oder einen Eintritt fehlt das Zeitfenster, oder das Zeitfenster existiert nicht.	Senden Sie einen `span` aus der Zeitfensterabfrage.
`requestItems.0.offerableId`	`invalid`	Das Angebot existiert nicht oder ist nicht veröffentlicht.	Laden Sie die Angebote neu.
`requestItems.0.offerableId`	`exclusively_booked`	Ein anderer Kunde hat die gesamte Veranstaltung exklusiv gebucht.	Lassen Sie den Kunden eine andere Veranstaltung wählen.
`resourceRequirements`	`no_available_resources`	Für die Buchung nötiges Personal oder nötige Räume sind zu dieser Zeit nicht verfügbar.	Lassen Sie den Kunden eine andere Zeit wählen.
`requestId`	`invalid`	Der Warenkorb existiert nicht oder seine Reservierung ist abgelaufen.	Legen Sie einen neuen Warenkorb an.
`requestId`	`not_editable`	Der Vorgang wurde storniert oder kann nicht mehr geändert werden, zum Beispiel nach der Zahlung.	Legen Sie für weitere Käufe einen neuen Warenkorb an.
`checkoutHold`	`expired`	Der Checkout-Hold ist abgelaufen und KORONA Event hat den Warenkorb storniert.	Legen Sie einen neuen Warenkorb an.
`id`	`locked`	Für diesen Warenkorb läuft gleichzeitig der Checkout.	Warten Sie kurz und lesen Sie den Warenkorb, bevor Sie es erneut versuchen.

Kundendaten

Diese Fehler kommen von requestUpdate.

Schlüssel	Code	Ursache	Vorgehen
`contact.email`	`blank`	Die E-Mail-Adresse fehlt.	Fragen Sie nach einer E-Mail-Adresse.
`contact.email`	`invalid_address`	Die E-Mail-Adresse ist ungültig.	Bitten Sie den Kunden, sie zu korrigieren.
`id`	`payment_exists`	Für diesen Warenkorb läuft eine Zahlung.	Ändern Sie den Warenkorb nicht. Verfolgen Sie die Zahlung über die Rechnung.
`id`	`already_canceled`	Der Warenkorb wurde storniert.	Legen Sie einen neuen Warenkorb an.

Codes

Diese Fehler kommen von requestApplyCode und requestRemoveCode.

Schlüssel	Code	Ursache	Vorgehen
`code`	`invalid`	Der Code ist unbekannt, abgelaufen, aufgebraucht, hat keinen Restwert, ist bereits eingelöst oder gilt nicht für den Warenkorb. Beim Entfernen: Der Code ist im Warenkorb nicht eingelöst.	Teilen Sie dem Kunden mit, dass der Code nicht verwendet werden kann.
`code`	`already_redeemed`	Ein Aktionscode hat sein Einlöselimit erreicht.	Teilen Sie dem Kunden mit, dass der Code nicht verwendet werden kann.
`requestItem`	`blank`	Der Gutschein muss gegen einen Artikel eingelöst werden. Das Ergebnis listet die Auswahl in `followUpProducts`.	Lassen Sie den Kunden einen Artikel wählen und lösen Sie den Code erneut mit `requestItem` ein.
`requestId`	`not_editable`	Der Vorgang kann nicht mehr geändert werden.	Legen Sie einen neuen Warenkorb an.

Buchungs- und Teilnehmerfragen

Diese Fehler kommen von requestCustomFieldsCollectionSubmit.

Schlüssel	Code	Ursache	Vorgehen
`customFieldsResponses.0.values.0.value`	`invalid`	Die Antwort passt nicht zum `type` der Frage, zum Beispiel eine ungültige E-Mail-Adresse oder eine unbekannte Option.	Bitten Sie den Kunden, die Antwort zu korrigieren.
`customFieldsResponses`	`invalid`	Eine Pflichtantwort fehlt, oder die Antworten gehören zu mehr als einer Position oder einem Ticket.	Senden Sie alle Pflichtantworten für jeweils eine Position oder ein Ticket.
`customFieldsResponses`	`already_completed`	Die Fragen sind bereits beantwortet.	Lesen Sie die offenen Fragen erneut.

Checkout

Diese Fehler kommen von requestPaymentInitiate, requestReserve und requestRequest. Die beiden letzteren melden dieselben Codes für rechtliche Dokumente, die Einwilligung zum vorzeitigen Beginn, checkoutPolicy und den Checkout-Hold. Korrigieren Sie bei Eingabevalidierungsfehlern die Eingabe, bevor Sie es erneut versuchen. Ein abgelaufener Checkout-Hold storniert den Warenkorb. Bei id:locked kann ein anderer Checkout noch abgeschlossen werden und den Warenkorb verändern; warten Sie und lesen Sie den Warenkorb sowie eine eventuell vorhandene Rechnung, bevor Sie entscheiden, ob der Checkout noch erforderlich ist.

Schlüssel	Code	Ursache	Vorgehen
`contact`	`blank`	Der Warenkorb hat keinen Kunden.	Fügen Sie den Kunden zuerst mit `requestUpdate` hinzu.
`legalDocumentAcceptances`	`missing_required`	Einem erforderlichen Rechtsdokument wurde nicht zugestimmt.	Zeigen Sie das Dokument an und senden Sie die Zustimmung.
`legalDocumentAcceptances.0.legalDocumentVersion`	`invalid`	Die zugestimmte Version ist nicht die aktuelle. Das Dokument hat sich geändert, nachdem es angezeigt wurde.	Laden Sie die Dokumente neu, zeigen Sie sie erneut an und senden Sie das neue `publishedAt`.
`legalDocumentAcceptances.0.legalDocumentId`	`invalid`	Das Dokument existiert nicht.	Laden Sie die Dokumente neu.
`withdrawalEarlyStartConsent`	`missing_required`	Eine Position braucht die Einwilligung des Kunden, dass die Leistung vor Ablauf der Widerrufsfrist beginnt.	Holen Sie die Einwilligung ein und senden Sie sie mit `accepted: true`.
`withdrawalEarlyStartConsent`	`invalid`	`requestItemIds` enthält nicht genau die Positionen, die eine Einwilligung brauchen.	Senden Sie die IDs aller Positionen mit `requiresWithdrawalEarlyStartConsent`.
`id`	`custom_fields_incomplete`	Erforderliche Buchungs- oder Teilnehmerangaben fehlen.	Leiten Sie den Kunden zu den gehosteten Seiten, die sie erfassen, oder erfassen Sie sie vor dem Checkout.
`checkoutPolicy`	`TARGET_STATE_CONFLICT`, `PAYMENT_METHOD_CONFLICT`	Der Warenkorb enthält Angebote, die nicht gemeinsam abgeschlossen werden können.	Teilen Sie den Warenkorb auf.
`checkoutHold`	`expired`	Der Checkout-Hold ist abgelaufen und der Warenkorb wurde storniert.	Legen Sie einen neuen Warenkorb an.
`id`	`locked`	Für diesen Warenkorb läuft bereits eine weitere Checkout-Anfrage.	Warten Sie und lesen Sie den Warenkorb sowie eine eventuell vorhandene Rechnung, bevor Sie entscheiden, ob der Checkout noch erforderlich ist.

Abgelaufene Checkout-Holds

Senden Sie genau eines der Token requestId (das Warenkorb-Token) oder invoiceToken an requestCancelExpiredCheckoutHold. Wenn ein anonymer Aufrufer beide weglässt, enthält die Antwort den Fehler Not authenticated auf oberster Ebene. Senden Sie eines der Token und versuchen Sie es erneut.

Die Mutation kann folgende Fehler im Mutationsergebnis zurückgeben:

Schlüssel	Code	Ursache	Vorgehen
`checkoutHold`	`not_expired`	Der Checkout-Hold läuft noch.	Warten Sie, bis `secondsRemaining` null erreicht.
`id`	`invalid`	Sowohl `requestId` als auch `invoiceToken` wurden gesendet.	Senden Sie genau eines davon.
`id`	`blank`	Ein authentifizierter Aufrufer hat sowohl `requestId` als auch `invoiceToken` weggelassen.	Senden Sie genau eines davon.

Datenverkehrsbeschränkungen und Wiederholungsversuche

Bei der Durchsetzung von Traffic-Limits zählt KORONA Event HTTP-Anfragen und ausgeführte Root-Felder separat. Aliase, mehrere Root-Felder und Stapelverarbeitungen verbrauchen das Budget in gleicher Höhe wie separate Ausführungen. Für Anmeldungen, Passwortzurücksetzungen, Kontoeröffnungen, Uploads und Zahlungsversuche gelten strengere Budgetgrenzen. Bei Massen-Uploads wird jede Datei einzeln gezählt. Anfragen können sich ein Budget über ihr Netzwerk, ein authentifiziertes Konto oder API-Zugangsdaten teilen. Das Aufteilen eines Stapels oder das Ändern eines Vorgangsnamens führt nicht zu einer Zurücksetzung des Budgets.

Die Grenzen für den Arbeitsaufwand berücksichtigen auch die vom Server berechneten Kosten einer validierten Abfrage sowie noch laufender Anfragen. Ein Stapel umfasst die Kosten seiner Operationen. E-Mail-auslösende Aktionen und ressourcenintensive Vorgänge wie die Berechnung von Kalenderdaten, Massenänderungen, das Rendern von Dokumenten sowie die Einleitung eines Exports verfügen über separate Budgets. Ein Versuch, eine E-Mail auszulösen, ist keine Bestätigung dafür, dass eine E-Mail zugestellt wurde.

Falls eine Grenze für den Arbeitsaufwand eine Anfrage ablehnt, reduzieren Sie unnötig ausgewählte Felder, Datumsbereiche oder den Umfang von Masseneingaben und begrenzen Sie die Anzahl paralleler Anfragen. Warten Sie die angegebene Wartezeit ab, bevor Sie den Versuch wiederholen. Halten Sie die Abfrage des Zahlungsstatus begrenzt und verwenden Sie bereits vorliegende Ergebnisse wieder. Ein Platz für die parallele Verarbeitung wird frei, sobald ein Vorgang abgeschlossen ist; eine unterbrochene Verbindung zu einem Client bedeutet nicht zwangsläufig, dass eine Zahlung oder eine Änderung abgebrochen wurde. Überprüfen Sie daher den aktuellen Status, bevor Sie einen erneuten Versuch unternehmen.

Antwort	Bedeutung	Sichere Wiederherstellung
HTTP `429`, Fehlercode `RATE_LIMITED`	Die HTTP-Anfrage wurde vor der Ausführung von GraphQL abgelehnt.	Warten Sie mindestens die in `Retry-After` angegebene Anzahl von Sekunden, bevor Sie es erneut versuchen.
HTTP `503`, Fehlercode `RATE_LIMIT_UNAVAILABLE`	Die Anfrage konnte nicht sicher verarbeitet werden, und es wurde kein GraphQL-Feld ausgeführt.	Warten Sie die in `Retry-After` angegebene Anzahl von Sekunden, bevor Sie es erneut versuchen.
HTTP `200`, Fehler auf oberster Ebene mit `extensions.code: RATE_LIMITED`	Das durch `path` identifizierte Feld wurde abgelehnt, bevor sein Resolver ausgeführt wurde. Andere Felder wurden möglicherweise erfolgreich verarbeitet.	Warten Sie `extensions.retryAfter` Sekunden. Überprüfen Sie `data` sowie den Wert `path` jedes Fehlers; wiederholen Sie nur die abgelehnten Operationen.
HTTP `200`, Fehler auf oberster Ebene mit `extensions.code: RATE_LIMIT_UNAVAILABLE`	Ein sensibles Feld konnte nicht sicher zur Ausführung zugelassen werden. Andere Felder können bereits erfolgreich ausgeführt worden sein.	Warten Sie `extensions.retryAfter` Sekunden ab und überprüfen Sie den aktuellen Warenkorb, die Rechnung oder die Zahlung, bevor Sie entscheiden, welche Operationen noch erforderlich sind.

Verwenden Sie eine begrenzte Wiederholungsrichtlinie mit einer kurzen zufälligen Verzögerung nach der angegebenen Wartezeit. Vermeiden Sie es, eine gesamte Mutation oder einen gesamten Stapel sofort erneut zu versuchen: Frühere Felder haben möglicherweise bereits Änderungen gespeichert oder eine Zahlung initiiert. Behalten Sie denselben Idempotenzschlüssel bei, wenn Sie einen logischen Zahlungsversuch erneut versuchen, der einen solchen unterstützt. Die Abfrage des Zahlungsstatus verbraucht das reguläre Root-Feld-Budget und nicht das strengere Zahlungsversuchs-Budget.

Bei einer Ablehnung aufgrund von Kosten- oder Parallelitätsgrenzen können diese GraphQL-Fehler ohne path zurückgegeben werden, bevor ein Feld der betroffenen Operation ausgeführt wird. Prüfen Sie jedes Stapelergebnis einzeln; eine andere Operation kann bereits abgeschlossen sein.

Allgemeine Codes

Andere Eingaben verwenden diese allgemeinen Codes.

Code	Bedeutung
`blank`, `required`	Ein erforderlicher Wert fehlt.
`invalid`	Der Wert ist nicht zulässig oder existiert nicht.
`taken`	Der Wert muss eindeutig sein und wird bereits verwendet.
`greater_than_or_equal_to`, `less_than_or_equal_to`	Der Wert liegt unter dem Minimum oder über dem Maximum.