Fehlercodes.

Ursache: Kein Billing-Kunde mit dieser externalId – er entsteht beim ersten Abo oder mit upsertCustomer().

Lösung: Zuerst upsertCustomer({ externalId, email, name }) aufrufen oder die Id prüfen.

Ursache: Die planId ist nicht unter den plans, die du subkit() übergibst.

Lösung: Eine Id aus den konfigurierten Plänen verwenden (das MCP-Tool list_plans listet sie).

Ursache: Der Plan hat für dieses Intervall keinen Preis, oder er ist versteckt (wird nicht mehr verkauft).

Lösung: Nur die Intervalle aus plan.prices anbieten. Ein versteckter Plan bleibt bei seinen Abonnenten, ist aber nicht mehr kaufbar.

Ursache: Der Kunde hat schon ein laufendes Abo.

Lösung: Den Plan mit changePlan() wechseln statt subscribe() aufzurufen.

Ursache: Die Aktion braucht ein laufendes Abo, und der Kunde hat keines (nie abonniert, oder es ist abgelaufen).

Lösung: Mit subscribe() eines starten. getOverview() zeigt den aktuellen Stand.

Ursache: Im aktuellen Zustand nicht möglich: Der Checkout des Abos ist nicht abgeschlossen, oder eine offene Rechnung muss vor dem Planwechsel beglichen werden.

Lösung: Checkout abschliessen oder abbrechen, oder die offene Rechnung bezahlen, dann nochmals versuchen.

Ursache: Ein Upgrade wird sofort belastet und braucht eine gespeicherte Karte oder TWINT – es ist keine hinterlegt.

Lösung: Den Kunden eine hinterlegen lassen (POST …/payment-method) oder auf Rechnung umstellen.

Ursache: Die Belastung eines Upgrades wurde abgelehnt (Karte abgelehnt, zu wenig Guthaben, TWINT verweigert). Der Plan bleibt, wie er war.

Lösung: Den Kunden bitten, das Zahlungsmittel zu aktualisieren, dann nochmals versuchen.

Ursache: Der Zahlungsanbieter war nicht erreichbar oder hat mit einem Fehler geantwortet (keine abgelehnte Karte).

Lösung: Später nochmals versuchen. Status des Anbieters und API-Key prüfen (zahls.ch: Instanz und Key).

Ursache: Keine Rechnung mit dieser Id für diesen Kunden – oder beim Bezahlen keine offene.

Lösung: Die Id prüfen und ob die Rechnung zum angemeldeten Kunden gehört.

Ursache: Eine Rechnung des Kunden ist überfällig oder abgeschrieben; bis sie bezahlt ist, wird nichts Neues verkauft.

Lösung: Zuerst sie bezahlen (POST …/invoices/:id/pay oder per QR-Rechnung), dann nochmals versuchen.

Ursache: Diese Zahlungsart (Karte / TWINT oder Rechnung) ist in collectionMethods des Handlers nicht aktiviert.

Lösung: Sie in collectionMethods aufnehmen oder nur die aktivierten anbieten.

Ursache: Eine andere Anfrage ändert gerade dasselbe Abo, dieselbe Bestellung, denselben Warenkorb oder Lagerbestand (z. B. eine Verlängerung oder ein Webhook).

Lösung: Gleich nochmals versuchen – es geht nichts verloren.

Ursache: Dein Callback rateLimit hat die Anfrage abgelehnt, oder zu viele Webhooks für eine Zahlung kamen an.

Lösung: Die Sekunden aus Retry-After warten. Stossen echte Kundinnen und Kunden an das Limit, es erhöhen.

Ursache: Ein Webhook liess sich nicht prüfen: unbekannte Transaktion, Betrag oder Währung weichen ab, oder der Body ist kein JSON.

Lösung: Den Webhook des Anbieters (Format JSON) auf …/webhook zeigen lassen und dieselbe Instanz und denselben API-Key wie im Kit verwenden. Gefälschte Anfragen enden absichtlich hier.

Ursache: Der Callback authorize (oder identify) des Handlers hat die Anfrage nicht akzeptiert – keine Session oder kein Zugriff.

Lösung: Session-Cookie oder Token mitschicken und den Callback prüfen.

Ursache: Ein POST ohne Content-Type: application/json. Die Handler verlangen ihn als CSRF-Schutz.

Lösung: JSON mit genau diesem Content-Type senden – die React-Clients der Kits tun das bereits.

Ursache: Der Body der Anfrage ist kein gültiges JSON.

Lösung: Ein JSON-Objekt als Body senden.

Ursache: Ein Feld fehlt, hat den falschen Typ oder liegt ausserhalb des erlaubten Bereichs (z. B. unbekanntes Intervall, negativer Betrag, Link ohne http(s)).

Lösung: Das Feld aus der Meldung mit dem README des Kits abgleichen.

Ursache: Keine Route für diese Methode und diesen Pfad unter dem basePath des Handlers.

Lösung: Prüfen, ob basePath dem Ort der Route entspricht, und die HTTP-Methode prüfen.

Ursache: Ein unerwarteter Fehler (Datenbank, Bug). Die Details gehen nicht an den Client.

Lösung: onError und das Server-Log ansehen. Ein Bug in einem Kit: mit Stacktrace melden.

Ursache: Kein Produkt mit dieser Id oder diesem Slug.

Lösung: Id oder Slug prüfen. Archivierte Produkte gibt es nur im Backoffice.

Ursache: Keine Variante mit dieser Id.

Lösung: Eine Id aus product.variants verwenden.

Ursache: Das Produkt oder die Variante ist ein Entwurf oder archiviert.

Lösung: Im Backoffice aktivieren oder aus dem Warenkorb entfernen.

Ursache: Weniger an Lager als verlangt (der Bestand wird beim Checkout reserviert).

Lösung: Die Menge verringern – die Meldung nennt, wie viele noch da sind.

Ursache: Eine Menge unter 1 oder über dem Maximum pro Position, oder zu viele Artikel im Warenkorb.

Lösung: Eine ganze Zahl innerhalb der Grenze aus der Meldung verwenden.

Ursache: Kein Warenkorb mit diesem Token (falscher Token oder ein alter, aufgegebener Warenkorb).

Lösung: Einen neuen Warenkorb anlegen – der React-Provider tut das selbst.

Ursache: Checkout eines Warenkorbs ohne Artikel.

Lösung: Zuerst Artikel hinzufügen.

Ursache: Aus dem Warenkorb wurde schon eine Bestellung.

Lösung: Die Bestellung zeigen oder einen neuen Warenkorb beginnen.

Ursache: Unbekannter, abgelaufener, inaktiver oder aufgebrauchter Rabattcode.

Lösung: Den Code im Backoffice prüfen (list_discounts).

Ursache: Der Code ist gültig, aber dieser Warenkorb erfüllt die Bedingungen nicht (Mindestbestellwert, Produkte).

Lösung: Die Bedingungen erfüllen oder den Code entfernen.

Ursache: Unbekannte, gesperrte oder abgelaufene Geschenkkarte, oder das Guthaben reicht nicht.

Lösung: Code (Bindestriche und Gross-/Kleinschreibung spielen keine Rolle) und Guthaben prüfen.

Ursache: Checkout ohne E-Mail-Adresse.

Lösung: email in den Warenkorbdetails setzen (updateCartDetails()).

Ursache: Physische Artikel brauchen eine Lieferadresse.

Lösung: shippingAddress in den Warenkorbdetails setzen.

Ursache: Physische Artikel, aber keine Versandart gewählt.

Lösung: shippingRateId auf eine der angebotenen Versandarten setzen.

Ursache: Die gewählte Versandart gibt es nicht, oder sie passt nicht zu diesem Warenkorb.

Lösung: Eine der shippingOptions des Warenkorbs wählen.

Ursache: Die gewählte Versandart hat einen Zeitplan (schedule), aber der Warenkorb hat noch keinen Abhol- oder Liefertag – oder kein Zeitfenster, obwohl es welche gibt.

Lösung: Einen Tag aus shippingOptions[].schedule.dates (und ein Zeitfenster aus timeWindows) mit updateCartDetails({ fulfillmentDate, fulfillmentWindow }) setzen.

Ursache: Der Tag oder das Zeitfenster wird nicht (mehr) angeboten: vor der Vorlaufzeit, nach dem Bestellschluss, an einem geschlossenen Tag oder ausserhalb von maxDays.

Lösung: Einen Tag aus den aktuellen schedule.dates der Versandart wählen – die Liste ändert sich mit der Zeit und den Produkten im Warenkorb.

Ursache: Die Zahlungsart (online oder Rechnung) wird für diesen Shop oder diese Bestellung nicht angeboten, oder es ist kein Anbieter konfiguriert.

Lösung: Anbieter und Zahlungsarten in createShop() konfigurieren oder eine andere Zahlungsart wählen.

Ursache: Der Kunde hat keine (solche) gespeicherte Zahlungsart: noch keine gespeichert, entfernt, vom Anbieter abgelehnt und deaktiviert, oder sie gehört einem anderen Kunden.

Lösung: Ohne useSavedPaymentMethod bestellen (Zahlungslink) und dabei mit savePaymentMethod: true eine Zahlungsart speichern lassen.

Ursache: Der zu zahlende Betrag weicht vom Betrag ab, den der Kunde bestätigt hat (expectedAmount) – etwa weil sich Preis, Rabatt oder Versand geändert hat. Es wurde nichts belastet.

Lösung: Die Bestellung neu berechnen (quoteOrder / quote_order), dem Kunden den neuen Betrag zeigen und mit dem bestätigten Betrag erneut bestellen.

Ursache: Keine Bestellung mit dieser Id, oder der Token des Bestelllinks passt nicht.

Lösung: Id und token des Bestelllinks prüfen.

Ursache: Im Zustand der Bestellung nicht möglich: schon bezahlt, nicht bezahlbar, noch nicht bezahlt (Rückerstattung), storniert.

Lösung: Zuerst status, paymentStatus und fulfillmentStatus der Bestellung lesen.

Ursache: Die Rückerstattung ist höher als der noch offene Betrag, oder die Geschenkkarten der Bestellung wurden schon eingelöst.

Lösung: Höchstens den Betrag aus der Meldung zurückerstatten.

Ursache: Ein Produkt-Slug, eine SKU oder ein Rabattcode mit diesem Wert existiert schon.

Lösung: Einen anderen wählen oder den bestehenden Eintrag ändern.

Ursache: Der Zahlungsanbieter war nicht erreichbar oder hat mit einem Fehler geantwortet (keine abgelehnte Karte).

Lösung: Später nochmals versuchen. Status des Anbieters und API-Key prüfen (zahls.ch: Instanz und Key).

Ursache: Eine andere Anfrage ändert gerade dasselbe Abo, dieselbe Bestellung, denselben Warenkorb oder Lagerbestand (z. B. eine Verlängerung oder ein Webhook).

Lösung: Gleich nochmals versuchen – es geht nichts verloren.

Ursache: Dein Callback rateLimit hat die Anfrage abgelehnt, oder zu viele Webhooks für eine Zahlung kamen an.

Lösung: Die Sekunden aus Retry-After warten. Stossen echte Kundinnen und Kunden an das Limit, es erhöhen.

Ursache: Ein Webhook liess sich nicht prüfen: unbekannte Transaktion, Betrag oder Währung weichen ab, oder der Body ist kein JSON.

Lösung: Den Webhook des Anbieters (Format JSON) auf …/webhook zeigen lassen und dieselbe Instanz und denselben API-Key wie im Kit verwenden. Gefälschte Anfragen enden absichtlich hier.

Ursache: Ein Bankimport, aber der Backoffice-Handler hat keinen Einzahlungsschein, um die Referenzen zu berechnen.

Lösung: receipts.paymentSlip (z. B. swissQrBill()) an createShopAdminHandler() übergeben.

Ursache: Die Bankdatei ist kein camt.053- oder camt.054-XML-Dokument.

Lösung: camt.054 (oder camt.053) im E-Banking als XML exportieren und als { "camt": "<?xml …" } senden.

Ursache: HS-Soft (WaWiAssist) hat die Anfrage abgelehnt: ungültiger API-Key, ein Kanal, den der Key nicht schreiben darf, ein gesperrtes Bestelldatum, eine schon fakturierte Bestellung oder ein unbekannter Artikel. error.details.type nennt den Grund.

Lösung: Den Grund beheben (API-Key bei HS-Soft prüfen, Datum oder Artikel korrigieren) und die Bestellung mit syncOrder(id, { force: true }) erneut senden. Unverändert wiederholen hilft nicht.

Ursache: HS-Soft war nicht erreichbar oder vorübergehend gestört (503, Zeitüberschreitung, Gateway-Fehler).

Lösung: syncOrders() versucht es nach retryMinutes selbst wieder. Steht die Bestellung auf uncertain, zuerst in WaWiAssist nachsehen, ob sie angekommen ist – erst dann erneut senden.

Ursache: Eine Position oder die Versandkosten der Bestellung haben keinen HS-Soft-Artikel – das Produkt stammt nicht aus dem Import.

Lösung: Das Produkt aus HS-Soft importieren, orders.articleId bzw. orders.shippingArticleId setzen oder die Bestellung mit orders.filter ausnehmen.

Ursache: Die Post hat die Anfrage abgelehnt: Client oder Scopes der Digital Commerce API, die Frankierlizenz, eine Kombination von Leistungen, die die Sendung nicht haben kann, eine Adresse, an die die Post nicht zustellen kann – oder eine Sendung ins Ausland (Etiketten gibt es für die Schweiz und Liechtenstein). error.details.errors nennt die Codes der Post (E2001 …).

Lösung: Den Grund beheben (Client und Scopes bei der Post prüfen, Lizenz, Leistungen der Versandart oder Adresse korrigieren) und das Etikett erneut erstellen. Unverändert wiederholen hilft nicht.

Ursache: Die Post war nicht erreichbar oder vorübergehend gestört (Zeitüberschreitung, 5xx, E9999).

Lösung: Das Etikett später erneut erstellen. Adressvorschläge und Adressprüfung im Checkout scheitern nicht daran – die Bestellung geht ohne sie weiter.

Ursache: Der Callback authorize (oder identify) des Handlers hat die Anfrage nicht akzeptiert – keine Session oder kein Zugriff.

Lösung: Session-Cookie oder Token mitschicken und den Callback prüfen.

Ursache: Ein POST ohne Content-Type: application/json. Die Handler verlangen ihn als CSRF-Schutz.

Lösung: JSON mit genau diesem Content-Type senden – die React-Clients der Kits tun das bereits.

Ursache: Der Body der Anfrage ist kein gültiges JSON.

Lösung: Ein JSON-Objekt als Body senden.

Ursache: Ein Feld fehlt, hat den falschen Typ oder liegt ausserhalb des erlaubten Bereichs (z. B. unbekanntes Intervall, negativer Betrag, Link ohne http(s)).

Lösung: Das Feld aus der Meldung mit dem README des Kits abgleichen.

Ursache: Keine Route für diese Methode und diesen Pfad unter dem basePath des Handlers.

Lösung: Prüfen, ob basePath dem Ort der Route entspricht, und die HTTP-Methode prüfen.

Ursache: Die Backoffice-API nimmt nur GET und POST an.

Lösung: Für Änderungen POST verwenden.

Ursache: Der Body der Anfrage ist zu gross (100 kB; Bankdateien 20 MB).

Lösung: Weniger senden – zum Beispiel eine grosse Bankdatei aufteilen.

Ursache: Ein unerwarteter Fehler (Datenbank, Bug). Die Details gehen nicht an den Client.

Lösung: onError und das Server-Log ansehen. Ein Bug in einem Kit: mit Stacktrace melden.