Codici di errore.

Causa: Nessun cliente di fatturazione con questo externalId – viene creato al primo abbonamento o con upsertCustomer().

Soluzione: Chiama prima upsertCustomer({ externalId, email, name }), oppure controlla l’id.

Causa: Il planId non è tra i plans passati a subkit().

Soluzione: Usa un id dei piani configurati (lo strumento MCP list_plans li elenca).

Causa: Il piano non ha un prezzo per questo intervallo, oppure è nascosto (non più in vendita).

Soluzione: Offri solo gli intervalli di plan.prices. Un piano nascosto resta ai suoi abbonati ma non si può più acquistare.

Causa: Il cliente ha già un abbonamento in corso.

Soluzione: Cambia piano con changePlan() invece di chiamare subscribe().

Causa: L’azione richiede un abbonamento in corso e il cliente non ne ha (mai abbonato, oppure è terminato).

Soluzione: Avviane uno con subscribe(). getOverview() mostra lo stato attuale.

Causa: Non possibile nello stato attuale: il checkout dell’abbonamento non è concluso, oppure una fattura aperta va saldata prima di un cambio di piano.

Soluzione: Concludi o annulla il checkout, oppure paga la fattura aperta, poi riprova.

Causa: Un upgrade viene addebitato subito e richiede una carta o TWINT salvati – non ce ne sono.

Soluzione: Fai aggiungere al cliente un mezzo di pagamento (POST …/payment-method) oppure passa alla fattura.

Causa: L’addebito di un upgrade è stato rifiutato (carta rifiutata, fondi insufficienti, TWINT rifiutato). Il piano resta invariato.

Soluzione: Chiedi al cliente di aggiornare il mezzo di pagamento, poi riprova.

Causa: Il fornitore di pagamento non era raggiungibile o ha risposto con un errore (non si tratta di una carta rifiutata).

Soluzione: Riprova più tardi. Controlla lo stato del fornitore e la chiave API (zahls.ch: istanza e chiave).

Causa: Nessuna fattura con questo id per questo cliente – oppure, al momento del pagamento, nessuna fattura aperta.

Soluzione: Controlla l’id e che la fattura appartenga al cliente connesso.

Causa: Una fattura del cliente è scaduta o stralciata; finché non è pagata non si vende nulla di nuovo.

Soluzione: Pagala prima (POST …/invoices/:id/pay o con fattura QR), poi riprova.

Causa: Questa modalità di pagamento (carta / TWINT o fattura) non è attivata in collectionMethods dell’handler.

Soluzione: Aggiungila a collectionMethods, oppure offri solo le modalità attivate.

Causa: Un’altra richiesta sta modificando nello stesso momento lo stesso abbonamento, ordine, carrello o stock (p. es. un rinnovo o un webhook).

Soluzione: Riprova tra un attimo – non si perde nulla.

Causa: Il tuo callback rateLimit ha rifiutato la richiesta, oppure sono arrivati troppi webhook per un pagamento.

Soluzione: Attendi i secondi indicati in Retry-After. Se clienti reali raggiungono il limite, aumentalo.

Causa: Un webhook non ha potuto essere verificato: transazione sconosciuta, importo o valuta diversi, oppure il corpo non è JSON.

Soluzione: Fai puntare il webhook del fornitore (formato JSON) a …/webhook e usa la stessa istanza e la stessa chiave API del kit. Le richieste falsificate finiscono qui di proposito.

Causa: Il callback authorize (o identify) dell’handler non ha accettato la richiesta – nessuna sessione o nessun accesso.

Soluzione: Invia il cookie di sessione o il token con la richiesta e controlla il callback.

Causa: Un POST senza Content-Type: application/json. Gli handler lo richiedono come protezione CSRF.

Soluzione: Invia JSON con esattamente questo content type – i client React dei kit lo fanno già.

Causa: Il corpo della richiesta non è JSON valido.

Soluzione: Invia un oggetto JSON come corpo.

Causa: Un campo manca, ha il tipo sbagliato o è fuori dall’intervallo ammesso (p. es. intervallo sconosciuto, importo negativo, link non http(s)).

Soluzione: Confronta il campo indicato nel messaggio con il README del kit.

Causa: Nessuna route per questo metodo e percorso sotto il basePath dell’handler.

Soluzione: Verifica che basePath corrisponda al punto in cui è montata la route, e il metodo HTTP.

Causa: Un errore imprevisto (database, bug). I dettagli non vengono inviati al client.

Soluzione: Guarda onError e il log del server. Un bug in un kit: segnalalo con lo stack trace.

Causa: Nessun prodotto con questo id o slug.

Soluzione: Controlla id o slug. I prodotti archiviati sono solo nel back office.

Causa: Nessuna variante con questo id.

Soluzione: Usa un id di product.variants.

Causa: Il prodotto o la variante è una bozza o è archiviato.

Soluzione: Attivalo nel back office, oppure toglilo dal carrello.

Causa: In magazzino ci sono meno articoli di quelli richiesti (lo stock viene riservato al checkout).

Soluzione: Riduci la quantità – il messaggio indica quanti ne restano.

Causa: Una quantità inferiore a 1 o superiore al massimo per riga, oppure troppi articoli nel carrello.

Soluzione: Usa un numero intero entro il limite indicato nel messaggio.

Causa: Nessun carrello con questo token (token errato, oppure un vecchio carrello abbandonato).

Soluzione: Crea un nuovo carrello – il provider React lo fa da solo.

Causa: Checkout di un carrello senza articoli.

Soluzione: Aggiungi prima degli articoli.

Causa: Il carrello è già stato trasformato in un ordine.

Soluzione: Mostra l’ordine, oppure inizia un nuovo carrello.

Causa: Codice sconto sconosciuto, scaduto, inattivo o esaurito.

Soluzione: Controlla il codice nel back office (list_discounts).

Causa: Il codice è valido, ma questo carrello non soddisfa le condizioni (importo minimo, prodotti).

Soluzione: Soddisfa le condizioni, oppure rimuovi il codice.

Causa: Carta regalo sconosciuta, bloccata o scaduta, oppure saldo insufficiente.

Soluzione: Controlla il codice (trattini e maiuscole non contano) e il saldo.

Causa: Checkout senza indirizzo e-mail.

Soluzione: Imposta email nei dettagli del carrello (updateCartDetails()).

Causa: Gli articoli fisici richiedono un indirizzo di consegna.

Soluzione: Imposta shippingAddress nei dettagli del carrello.

Causa: Articoli fisici, ma nessuna modalità di spedizione scelta.

Soluzione: Imposta shippingRateId su una delle tariffe offerte.

Causa: La modalità di spedizione scelta non esiste o non è adatta a questo carrello.

Soluzione: Scegli una delle shippingOptions del carrello.

Causa: La modalità di spedizione scelta ha un calendario (schedule), ma il carrello non ha ancora un giorno di ritiro o consegna – o nessuna fascia oraria, anche se ce ne sono.

Soluzione: Imposta un giorno da shippingOptions[].schedule.dates (e una fascia da timeWindows) con updateCartDetails({ fulfillmentDate, fulfillmentWindow }).

Causa: Il giorno o la fascia oraria non è (più) offerto: prima del preavviso, dopo l’orario limite, in un giorno di chiusura o oltre maxDays.

Soluzione: Scegli un giorno tra le schedule.dates attuali della modalità di spedizione – l’elenco cambia nel tempo e con i prodotti nel carrello.

Causa: Il metodo di pagamento (online o fattura) non è offerto per questo shop o questo ordine, oppure non è configurato alcun fornitore.

Soluzione: Configura il fornitore e i metodi di pagamento in createShop(), oppure scegli un altro metodo.

Causa: Il cliente non ha (questo) metodo di pagamento salvato: nessuno ancora salvato, rimosso, rifiutato dal fornitore e disattivato, oppure appartiene a un altro cliente.

Soluzione: Ordina senza useSavedPaymentMethod (link di pagamento) e lascia che il cliente ne salvi uno con savePaymentMethod: true.

Causa: L’importo dovuto è diverso da quello confermato dal cliente (expectedAmount), ad esempio perché è cambiato un prezzo, uno sconto o la spedizione. Non è stato addebitato nulla.

Soluzione: Ricalcola l’ordine (quoteOrder / quote_order), mostra al cliente il nuovo importo e ordina di nuovo con l’importo confermato.

Causa: Nessun ordine con questo id, oppure il token del link dell’ordine non corrisponde.

Soluzione: Controlla l’id e il token del link dell’ordine.

Causa: Non possibile nello stato dell’ordine: già pagato, non pagabile, non ancora pagato (rimborso), annullato.

Soluzione: Leggi prima status, paymentStatus e fulfillmentStatus dell’ordine.

Causa: Il rimborso supera l’importo ancora rimborsabile, oppure le carte regalo dell’ordine sono già state usate.

Soluzione: Rimborsa al massimo l’importo indicato nel messaggio.

Causa: Esiste già uno slug di prodotto, uno SKU o un codice sconto con questo valore.

Soluzione: Scegline un altro, oppure modifica la voce esistente.

Causa: Il fornitore di pagamento non era raggiungibile o ha risposto con un errore (non si tratta di una carta rifiutata).

Soluzione: Riprova più tardi. Controlla lo stato del fornitore e la chiave API (zahls.ch: istanza e chiave).

Causa: Un’altra richiesta sta modificando nello stesso momento lo stesso abbonamento, ordine, carrello o stock (p. es. un rinnovo o un webhook).

Soluzione: Riprova tra un attimo – non si perde nulla.

Causa: Il tuo callback rateLimit ha rifiutato la richiesta, oppure sono arrivati troppi webhook per un pagamento.

Soluzione: Attendi i secondi indicati in Retry-After. Se clienti reali raggiungono il limite, aumentalo.

Causa: Un webhook non ha potuto essere verificato: transazione sconosciuta, importo o valuta diversi, oppure il corpo non è JSON.

Soluzione: Fai puntare il webhook del fornitore (formato JSON) a …/webhook e usa la stessa istanza e la stessa chiave API del kit. Le richieste falsificate finiscono qui di proposito.

Causa: Un’importazione bancaria, ma l’handler del back office non ha una polizza di versamento per calcolare i riferimenti.

Soluzione: Passa receipts.paymentSlip (p. es. swissQrBill()) a createShopAdminHandler().

Causa: Il file bancario non è un documento XML camt.053 o camt.054.

Soluzione: Esporta il camt.054 (o camt.053) in XML dall’e-banking e invialo come { "camt": "<?xml …" }.

Causa: HS-Soft (WaWiAssist) ha rifiutato la richiesta: chiave API non valida, un canale che la chiave non può scrivere, data d’ordine bloccata, ordine già fatturato o articolo sconosciuto. error.details.type indica il motivo.

Soluzione: Correggi la causa (verifica la chiave API presso HS-Soft, correggi la data o l’articolo) e invia di nuovo l’ordine con syncOrder(id, { force: true }). Ripetere senza modifiche non serve.

Causa: HS-Soft non era raggiungibile o aveva un disturbo temporaneo (503, timeout, errore del gateway).

Soluzione: syncOrders() riprova da solo dopo retryMinutes. Se l’ordine è uncertain, controlla prima in WaWiAssist se è arrivato – solo dopo invialo di nuovo.

Causa: Una posizione o le spese di spedizione dell’ordine non hanno un articolo HS-Soft – il prodotto non proviene dall’importazione.

Soluzione: Importa il prodotto da HS-Soft, imposta orders.articleId o orders.shippingArticleId, oppure escludi l’ordine con orders.filter.

Causa: La Posta ha rifiutato la richiesta: client o scope della Digital Commerce API, licenza d’affrancatura, combinazione di prestazioni non possibile per l’invio, indirizzo a cui la Posta non può recapitare – o invio all’estero (le etichette sono per la Svizzera e il Liechtenstein). error.details.errors indica i codici della Posta (E2001 …).

Soluzione: Correggi la causa (verifica client e scope presso la Posta, la licenza, le prestazioni della modalità di spedizione o l’indirizzo) e crea di nuovo l’etichetta. Ripetere senza modifiche non serve.

Causa: La Posta non era raggiungibile o aveva un disturbo temporaneo (timeout, 5xx, E9999).

Soluzione: Crea l’etichetta più tardi. Le proposte e la verifica dell’indirizzo nel checkout non falliscono per questo – l’ordine prosegue senza.

Causa: Il callback authorize (o identify) dell’handler non ha accettato la richiesta – nessuna sessione o nessun accesso.

Soluzione: Invia il cookie di sessione o il token con la richiesta e controlla il callback.

Causa: Un POST senza Content-Type: application/json. Gli handler lo richiedono come protezione CSRF.

Soluzione: Invia JSON con esattamente questo content type – i client React dei kit lo fanno già.

Causa: Il corpo della richiesta non è JSON valido.

Soluzione: Invia un oggetto JSON come corpo.

Causa: Un campo manca, ha il tipo sbagliato o è fuori dall’intervallo ammesso (p. es. intervallo sconosciuto, importo negativo, link non http(s)).

Soluzione: Confronta il campo indicato nel messaggio con il README del kit.

Causa: Nessuna route per questo metodo e percorso sotto il basePath dell’handler.

Soluzione: Verifica che basePath corrisponda al punto in cui è montata la route, e il metodo HTTP.

Causa: L’API di back office accetta solo GET e POST.

Soluzione: Usa POST per le modifiche.

Causa: Il corpo della richiesta è troppo grande (100 kB; file bancari 20 MB).

Soluzione: Invia meno dati – per esempio dividi un file bancario grande.

Causa: Un errore imprevisto (database, bug). I dettagli non vengono inviati al client.

Soluzione: Guarda onError e il log del server. Un bug in un kit: segnalalo con lo stack trace.