Codes d’erreur.

Cause: Aucun client de facturation avec cet externalId – il est créé au premier abonnement ou avec upsertCustomer().

Solution: Appelez d’abord upsertCustomer({ externalId, email, name }), ou vérifiez l’identifiant.

Cause: Le planId ne figure pas parmi les plans passés à subkit().

Solution: Utilisez un identifiant des plans configurés (l’outil MCP list_plans les liste).

Cause: Le plan n’a pas de prix pour cet intervalle, ou il est masqué (plus en vente).

Solution: Proposez seulement les intervalles de plan.prices. Un plan masqué reste chez ses abonnés mais ne peut plus être acheté.

Cause: Le client a déjà un abonnement en cours.

Solution: Changez de plan avec changePlan() au lieu d’appeler subscribe().

Cause: L’action nécessite un abonnement en cours, et le client n’en a pas (jamais abonné, ou abonnement terminé).

Solution: Démarrez-en un avec subscribe(). getOverview() montre l’état actuel.

Cause: Impossible dans l’état actuel : le paiement de l’abonnement n’est pas terminé, ou une facture ouverte doit être réglée avant un changement de plan.

Solution: Terminez ou annulez le paiement, ou payez la facture ouverte, puis réessayez.

Cause: Une montée en gamme est débitée immédiatement et nécessite une carte ou TWINT enregistré – il n’y en a pas.

Solution: Laissez le client en ajouter un (POST …/payment-method) ou passez à la facture.

Cause: Le débit d’une montée en gamme a été refusé (carte refusée, solde insuffisant, TWINT refusé). Le plan reste inchangé.

Solution: Demandez au client de mettre à jour son moyen de paiement, puis réessayez.

Cause: Le prestataire de paiement était injoignable ou a répondu par une erreur (il ne s’agit pas d’une carte refusée).

Solution: Réessayez plus tard. Vérifiez l’état du prestataire et la clé d’API (zahls.ch : instance et clé).

Cause: Aucune facture avec cet identifiant pour ce client – ou, lors du paiement, aucune facture ouverte.

Solution: Vérifiez l’identifiant et que la facture appartient au client connecté.

Cause: Une facture du client est en retard ou passée en perte ; rien de nouveau n’est vendu tant qu’elle n’est pas payée.

Solution: Payez-la d’abord (POST …/invoices/:id/pay ou par facture QR), puis réessayez.

Cause: Ce mode de paiement (carte / TWINT ou facture) n’est pas activé dans collectionMethods du handler.

Solution: Ajoutez-le à collectionMethods, ou ne proposez que les modes activés.

Cause: Une autre requête modifie au même moment le même abonnement, la même commande, le même panier ou le même stock (p. ex. un renouvellement ou un webhook).

Solution: Réessayez dans un instant – rien n’est perdu.

Cause: Votre callback rateLimit a refusé la requête, ou trop de webhooks sont arrivés pour un paiement.

Solution: Attendez les secondes indiquées dans Retry-After. Si de vrais clients atteignent la limite, augmentez-la.

Cause: Un webhook n’a pas pu être vérifié : transaction inconnue, montant ou devise différents, ou corps qui n’est pas du JSON.

Solution: Faites pointer le webhook du prestataire (format JSON) vers …/webhook et utilisez la même instance et la même clé d’API que le kit. Les requêtes falsifiées s’arrêtent ici volontairement.

Cause: Le callback authorize (ou identify) du handler n’a pas accepté la requête – pas de session ou pas d’accès.

Solution: Envoyez le cookie de session ou le jeton avec la requête et vérifiez le callback.

Cause: Un POST sans Content-Type: application/json. Les handlers l’exigent comme protection CSRF.

Solution: Envoyez du JSON avec exactement ce content type – les clients React des kits le font déjà.

Cause: Le corps de la requête n’est pas du JSON valide.

Solution: Envoyez un objet JSON comme corps.

Cause: Un champ manque, a un mauvais type ou sort de la plage permise (p. ex. intervalle inconnu, montant négatif, lien qui n’est pas en http(s)).

Solution: Comparez le champ indiqué dans le message avec le README du kit.

Cause: Aucune route pour cette méthode et ce chemin sous le basePath du handler.

Solution: Vérifiez que basePath correspond à l’emplacement de la route, ainsi que la méthode HTTP.

Cause: Une erreur inattendue (base de données, bug). Les détails ne sont pas envoyés au client.

Solution: Consultez onError et le journal du serveur. Un bug dans un kit : signalez-le avec la stack trace.

Cause: Aucun produit avec cet identifiant ou ce slug.

Solution: Vérifiez l’identifiant ou le slug. Les produits archivés ne sont que dans le back-office.

Cause: Aucune variante avec cet identifiant.

Solution: Utilisez un identifiant de product.variants.

Cause: Le produit ou la variante est un brouillon ou archivé.

Solution: Activez-le dans le back-office, ou retirez-le du panier.

Cause: Moins d’articles en stock que demandé (le stock est réservé au paiement).

Solution: Réduisez la quantité – le message indique combien il en reste.

Cause: Une quantité inférieure à 1 ou supérieure au maximum par ligne, ou trop d’articles dans le panier.

Solution: Utilisez un nombre entier dans la limite indiquée par le message.

Cause: Aucun panier avec ce jeton (jeton erroné, ou ancien panier abandonné).

Solution: Créez un nouveau panier – le provider React le fait tout seul.

Cause: Paiement d’un panier sans articles.

Solution: Ajoutez d’abord des articles.

Cause: Le panier a déjà été transformé en commande.

Solution: Affichez la commande, ou commencez un nouveau panier.

Cause: Code de réduction inconnu, expiré, inactif ou épuisé.

Solution: Vérifiez le code dans le back-office (list_discounts).

Cause: Le code est valable, mais ce panier ne remplit pas les conditions (montant minimum, produits).

Solution: Remplissez les conditions, ou retirez le code.

Cause: Carte cadeau inconnue, bloquée ou expirée, ou solde insuffisant.

Solution: Vérifiez le code (les tirets et la casse n’ont pas d’importance) et le solde.

Cause: Paiement sans adresse e-mail.

Solution: Renseignez email dans les détails du panier (updateCartDetails()).

Cause: Les articles physiques nécessitent une adresse de livraison.

Solution: Renseignez shippingAddress dans les détails du panier.

Cause: Des articles physiques, mais aucun mode d’envoi choisi.

Solution: Définissez shippingRateId sur l’un des tarifs proposés.

Cause: Le mode d’envoi choisi n’existe pas ou ne convient pas à ce panier.

Solution: Choisissez l’une des shippingOptions du panier.

Cause: Le mode d’envoi choisi a un calendrier (schedule), mais le panier n’a pas encore de jour de retrait ou de livraison – ou pas de créneau alors qu’il y en a.

Solution: Définissez un jour de shippingOptions[].schedule.dates (et un créneau de timeWindows) avec updateCartDetails({ fulfillmentDate, fulfillmentWindow }).

Cause: Le jour ou le créneau n’est pas (plus) proposé : avant le délai, après l’heure limite, un jour de fermeture ou au-delà de maxDays.

Solution: Choisissez un jour des schedule.dates actuelles du mode d’envoi – la liste change avec le temps et les produits du panier.

Cause: Le mode de paiement (en ligne ou facture) n’est pas proposé pour cette boutique ou cette commande, ou aucun prestataire n’est configuré.

Solution: Configurez le prestataire et les modes de paiement dans createShop(), ou choisissez un autre mode.

Cause: Le client n’a pas (ce) mode de paiement enregistré : aucun enregistré, supprimé, refusé par le prestataire et désactivé, ou il appartient à un autre client.

Solution: Commandez sans useSavedPaymentMethod (lien de paiement) et laissez le client en enregistrer un avec savePaymentMethod: true.

Cause: Le montant dû diffère de celui confirmé par le client (expectedAmount), par exemple parce qu’un prix, un rabais ou la livraison a changé. Rien n’a été débité.

Solution: Recalculez la commande (quoteOrder / quote_order), montrez le nouveau montant au client et commandez à nouveau avec le montant confirmé.

Cause: Aucune commande avec cet identifiant, ou le jeton du lien de commande ne correspond pas.

Solution: Vérifiez l’identifiant et le token du lien de commande.

Cause: Impossible dans l’état de la commande : déjà payée, impossible à payer, pas encore payée (remboursement), annulée.

Solution: Lisez d’abord status, paymentStatus et fulfillmentStatus de la commande.

Cause: Le remboursement dépasse le montant restant à rembourser, ou les cartes cadeaux de la commande ont déjà été utilisées.

Solution: Remboursez au plus le montant indiqué dans le message.

Cause: Un slug de produit, un SKU ou un code de réduction avec cette valeur existe déjà.

Solution: Choisissez-en un autre, ou modifiez l’entrée existante.

Cause: Le prestataire de paiement était injoignable ou a répondu par une erreur (il ne s’agit pas d’une carte refusée).

Solution: Réessayez plus tard. Vérifiez l’état du prestataire et la clé d’API (zahls.ch : instance et clé).

Cause: Une autre requête modifie au même moment le même abonnement, la même commande, le même panier ou le même stock (p. ex. un renouvellement ou un webhook).

Solution: Réessayez dans un instant – rien n’est perdu.

Cause: Votre callback rateLimit a refusé la requête, ou trop de webhooks sont arrivés pour un paiement.

Solution: Attendez les secondes indiquées dans Retry-After. Si de vrais clients atteignent la limite, augmentez-la.

Cause: Un webhook n’a pas pu être vérifié : transaction inconnue, montant ou devise différents, ou corps qui n’est pas du JSON.

Solution: Faites pointer le webhook du prestataire (format JSON) vers …/webhook et utilisez la même instance et la même clé d’API que le kit. Les requêtes falsifiées s’arrêtent ici volontairement.

Cause: Un import bancaire, mais le handler de back-office n’a pas de bulletin de versement pour calculer les références.

Solution: Passez receipts.paymentSlip (p. ex. swissQrBill()) à createShopAdminHandler().

Cause: Le fichier bancaire n’est pas un document XML camt.053 ou camt.054.

Solution: Exportez le camt.054 (ou camt.053) en XML depuis l’e-banking et envoyez-le sous la forme { "camt": "<?xml …" }.

Cause: HS-Soft (WaWiAssist) a refusé la requête : clé API invalide, canal que la clé ne peut pas écrire, date de commande verrouillée, commande déjà facturée ou article inconnu. error.details.type en donne la raison.

Solution: Corrigez la cause (vérifiez la clé API auprès de HS-Soft, corrigez la date ou l’article) et renvoyez la commande avec syncOrder(id, { force: true }). Répéter sans changement ne sert à rien.

Cause: HS-Soft n’était pas joignable ou était temporairement en panne (503, délai dépassé, erreur de passerelle).

Solution: syncOrders() réessaie lui-même après retryMinutes. Si la commande est uncertain, vérifiez d’abord dans WaWiAssist si elle est arrivée – ne la renvoyez qu’ensuite.

Cause: Une position ou les frais d’envoi de la commande n’ont pas d’article HS-Soft – le produit ne provient pas de l’import.

Solution: Importez le produit depuis HS-Soft, définissez orders.articleId ou orders.shippingArticleId, ou excluez la commande avec orders.filter.

Cause: La Poste a refusé la requête : client ou scopes de la Digital Commerce API, licence d’affranchissement, combinaison de prestations impossible pour l’envoi, adresse où La Poste ne peut pas distribuer – ou envoi à l’étranger (les étiquettes sont pour la Suisse et le Liechtenstein). error.details.errors donne les codes de La Poste (E2001 …).

Solution: Corrigez la cause (vérifiez le client et les scopes auprès de La Poste, la licence, les prestations du mode d’envoi ou l’adresse) et créez l’étiquette à nouveau. Répéter sans changement ne sert à rien.

Cause: La Poste n’était pas joignable ou était temporairement en panne (délai dépassé, 5xx, E9999).

Solution: Créez l’étiquette plus tard. Les propositions et la vérification d’adresse du checkout n’échouent pas pour autant – la commande continue sans elles.

Cause: Le callback authorize (ou identify) du handler n’a pas accepté la requête – pas de session ou pas d’accès.

Solution: Envoyez le cookie de session ou le jeton avec la requête et vérifiez le callback.

Cause: Un POST sans Content-Type: application/json. Les handlers l’exigent comme protection CSRF.

Solution: Envoyez du JSON avec exactement ce content type – les clients React des kits le font déjà.

Cause: Le corps de la requête n’est pas du JSON valide.

Solution: Envoyez un objet JSON comme corps.

Cause: Un champ manque, a un mauvais type ou sort de la plage permise (p. ex. intervalle inconnu, montant négatif, lien qui n’est pas en http(s)).

Solution: Comparez le champ indiqué dans le message avec le README du kit.

Cause: Aucune route pour cette méthode et ce chemin sous le basePath du handler.

Solution: Vérifiez que basePath correspond à l’emplacement de la route, ainsi que la méthode HTTP.

Cause: L’API de back-office n’accepte que GET et POST.

Solution: Utilisez POST pour les modifications.

Cause: Le corps de la requête est trop volumineux (100 kB ; fichiers bancaires 20 MB).

Solution: Envoyez moins – divisez par exemple un gros fichier bancaire.

Cause: Une erreur inattendue (base de données, bug). Les détails ne sont pas envoyés au client.

Solution: Consultez onError et le journal du serveur. Un bug dans un kit : signalez-le avec la stack trace.