Codici di Errore

​

Panoramica

• Un codice di stato HTTP che indica la categoria generale dell’errore
• Un codice di errore specifico che identifica la natura esatta dell’errore
• Un messaggio di errore leggibile dall’uomo che spiega cosa è andato storto
• Dettagli aggiuntivi sull’errore quando applicabile

• Risolvere problemi di integrazione
• Implementare una corretta gestione degli errori nella tua applicazione
• Fornire feedback significativi agli utenti finali
• Mantenere un sistema di elaborazione dei pagamenti robusto

​

Codici di Errore API Standard

​

Formato della Risposta di Errore

{
  "code": "UNSUPPORTED_COUNTRY",
  "message": "Country AI currently not supported"
}

​

Riferimento ai Codici di Errore

​

Autenticazione & Account

• UNAUTHORIZED
  • Trigger: Nessuna chiave API o token / ambito non valido
  • Messaggio: Non sei autorizzato a eseguire questa azione
• MERCHANT_NOT_LIVE
  • Trigger: Attività ancora in modalità test/sandbox
  • Messaggio: Il commerciante non è in modalità live

​

Pagamenti & Checkout

• CHECKOUT_SESSION_CONSUMED
  • Trigger: La sessione di checkout ha già generato un pagamento
  • Messaggio: La sessione di checkout è già stata consumata
• NO_ELIGIBLE_PAYMENT_METHODS
  • Trigger: Dopo il filtraggio, niente resta
  • Messaggio: Nessun metodo di pagamento idoneo trovato
• PAYMENT_NOT_SUCCEEDED
  • Trigger: Tentativo di rimborso/elaborazione di pagamento non riuscito
  • Messaggio: Il pagamento fornito non è riuscito
• PREVIOUS_PAYMENT_PENDING
  • Trigger: Tentativo di creare un addebito mentre il precedente è in stato non terminale
  • Messaggio: Impossibile creare un nuovo addebito poiché il pagamento precedente non è ancora riuscito
• UNSUCCESSFUL_PAYMENT_ID
  • Trigger: ID pagamento riferisce a un pagamento non riuscito
  • Messaggio: L’ID pagamento ha uno stato non riuscito.

​

Connettori & BYOP

• BYOP_CONNECTOR_DISABLED
  • Trigger: Aggiornamento di un metodo di pagamento su un abbonamento instradato tramite un connettore BYOP disabilitato
  • Messaggio: L’abbonamento è instradato tramite il connettore proprio del commerciante (BYOP) attualmente disabilitato
• BYOP_CUSTOM_INVOICE_ADDRESS_MISSING
  • Trigger: Un pagamento instradato dal commerciante (BYOP) manca dell’indirizzo fattura personalizzato richiesto
  • Messaggio: Indirizzo fattura personalizzato BYOP richiesto quando un pagamento è instradato tramite il connettore del commerciante
• CONNECTOR_LABEL_ALREADY_EXISTS
  • Trigger: Creazione di un connettore con un’etichetta già esistente
  • Messaggio: Esiste già un connettore con questa etichetta. Si prega di scegliere un’etichetta diversa.

​

Rimborsi

• EXISTING_REFUND_REQUEST_PROCESSING
  • Trigger: La precedente richiesta di rimborso è ancora in elaborazione
  • Message: Una richiesta di rimborso con stato “Pending” è ancora in elaborazione
• LINE_ITEM_FULLY_REFUNDED
  • Trigger: Tentativo di rimborso di un articolo già rimborsato completamente
  • Messaggio: Voce di fila è stata completamente rimborsata non può essere rimborsata ulteriormente.
• LINE_ITEM_NOT_FOUND
  • Trigger: ID articolo non fa parte del pagamento di riferimento
  • Messaggio: Voce di fila non trovata nel pagamento
• LINE_ITEM_PRORATED
  • Trigger: Tentativo di rimborso o aggiornamento su una linea prorata
  • Messaggio: Voce di fila non può essere rimborsata perché è prorata
• LINE_ITEM_REFUND_AMOUNT_TOO_HIGH
  • Trigger: Importo del rimborso > importo pagato (tasse incluse)
  • Messaggio: La richiesta di rimborso della voce di fila inclusa di tasse è che è oltre l’importo pagato
• LINE_ITEM_REFUND_AMOUNT_TOO_LOW
  • Trigger: Importo del rimborso sotto la soglia minima
  • Messaggio: La richiesta di rimborso della voce di fila è che è troppo bassa
• NOTHING_TO_REFUND
  • Trigger: Nessun importo rimborsabile rimasto; tutte le voci di fila positive già completamente rimborsate
  • Messaggio: Nessun importo rimborsabile rimasto. Tutte le voci di fila positive sono state completamente rimborsate.
• PARTIAL_REFUND_NOT_ALLOWED
  • Trigger: Tentativo di rimborso parziale su un metodo di pagamento che supporta solo rimborsi completi
  • Messaggio: I rimborsi parziali non sono consentiti per questo metodo di pagamento
• PAYMENT_ALREADY_REFUNDED
  • Trigger: Rimborso duplicato
  • Messaggio: Questo pagamento è già stato rimborsato
• PAYMENT_HAS_BEEN_REFUNDED
  • Trigger: Pagamento è stato completamente rimborsato
  • Messaggio: L’ID pagamento è stato completamente rimborsato.
• REFUND_AMOUNT_EXCEEDS_PAID_AMOUNT
  • Trigger: Importo aggregato del rimborso > importo pagato
  • Messaggio: L’importo calcolato del rimborso è maggiore dell’importo pagato
• REFUND_WINDOW_EXPIRED
  • Trigger: Fuori dalla finestra temporale consentita per il rimborso
  • Messaggio: I rimborsi non possono essere iniziati giorni dopo la creazione del pagamento. Contatta support@dodopayments.com.
• ZERO_AMOUNT_PAYMENT_REFUND_NOT_ALLOWED
  • Trigger: Tentativo di rimborso di un pagamento di importo zero
  • Messaggio: Impossibile rimborsare un pagamento con importo valuta zero

​

Abbonamenti & Add-on

• ADDONS_IN_USAGE_BASED_BILLING_NOT_SUPPORTED
  • Trigger: Tentativo di aggiungere add-on agli abbonamenti basati sull’uso
  • Messaggio: Gli add-on negli abbonamenti non sono supportati per la fatturazione basata sull’uso
• ADDONS_NOT_ALLOWED_FOR_ON_DEMAND
  • Trigger: Tentativo di aggiungere add-on agli abbonamenti su richiesta
  • Messaggio: Gli add-on non sono consentiti per gli abbonamenti su richiesta
• CANCEL_SCHEDULED_PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED
  • Trigger: Il portale clienti tenta di annullare un cambio piano programmato mentre l’azienda ha disabilitato tale azione
  • Messaggio: L’annullamento del cambio piano programmato è disabilitato per il portale clienti.
• CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • Trigger: Tentativo di addebitare un abbonamento programmato per l’annullamento
  • Messaggio: Abbonamento programmato per l’annullamento
• CUSTOMER_HAS_EXISTING_SUBSCRIPTION
  • Trigger: Creazione di un abbonamento per un cliente che ne ha già uno, quando più abbonamenti per cliente non sono consentiti
  • Messaggio: Il cliente ha già un abbonamento esistente. Per consentire più abbonamenti per cliente, modifica le impostazioni aziendali
• DO_NOT_BILL_NOT_ALLOWED_IN_CUSTOMER_PORTAL
  • Trigger: Modalità di proratazione do_not_bill utilizzata in un cambio piano del portale clienti
  • Messaggio: La modalità di proratazione do_not_bill non è consentita nel portale clienti
• DUPLICATE_ADDON_IDS_IN_REQUEST
  • Trigger: Lo stesso addon_id appare più di una volta nella richiesta
  • Messaggio: ID degli add-on duplicati non sono consentiti
• INACTIVE_SUBSCRIPTION_PLAN_CHANGE_NOT_SUPPORTED
  • Trigger: Cambio piano su abbonamento inattivo
  • Messaggio: Cambiare piani non è supportato per gli abbonamenti inattivi
• INVALID_PRORATION_MODE_WITH_NEXT_BILLING_DATE
  • Trigger: Una modalità di proratazione diversa da full_immediately utilizzata con effective_at: next_billing_date
  • Messaggio: Solo la modalità di proratazione full_immediately è consentita con effective_at: next_billing_date
• MISSING_ADDON_IDS
  • Trigger: Lista di addon_id vuota o ID sconosciuti
  • Messaggio: Uno o più ID prodotto non esistono:
• ON_DEMAND_PLAN_CHANGE_NOT_SUPPORTED
  • Trigger: Cambio piano non consentito per su richiesta
  • Messaggio: Cambiare piani non è supportato per gli abbonamenti su richiesta
• ON_DEMAND_USAGE_BASED_BILLING_NOT_SUPPORTED
  • Trigger: Tentativo di utilizzare con fatturazione basata sull’uso
  • Messaggio: Gli abbonamenti su richiesta non sono supportati per la fatturazione basata sull’uso
• ONE_TIME_PRODUCTS_NOT_ALLOWED_FOR_ON_DEMAND
  • Trigger: Prodotto una tantum aggiunto a un abbonamento su richiesta
  • Messaggio: I prodotti una tantum non sono consentiti per gli abbonamenti su richiesta
• PENDING_PLAN_CHANGE_EXISTS
  • Trigger: Nuovo cambio piano richiesto mentre uno precedente è ancora in attesa di pagamento
  • Messaggio: Esiste già un cambio piano pendente per questo abbonamento. Si prega di attendere il completamento del pagamento corrente.
• PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED
  • Trigger: Cambio piano tramite il Portale Clienti mentre l’azienda lo ha disabilitato
  • Messaggio: Il cambio del piano di abbonamento per il portale clienti è disabilitato.
• PLAN_CHANGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • Trigger: Tentativo di cambio piano su abbonamento programmato per l’annullamento
  • Messaggio: Abbonamento programmato per l’annullamento
• SCHEDULE_PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED
  • Trigger: Programmazione di un cambio piano tramite il Portale Clienti mentre l’azienda lo ha disabilitato
  • Messaggio: La programmazione dei cambiamenti di piano è disabilitata per questa azienda.
• SCHEDULED_PLAN_CHANGE_EXISTS
  • Trigger: Creazione di un cambio piano programmato quando uno è già esistente
  • Messaggio: Esiste già un cambio piano programmato per questo abbonamento. Si prega di annullare l’esistente cambiamento programmato prima di crearne uno nuovo.
• SCHEDULED_PLAN_CHANGE_NOT_FOUND
  • Trigger: Riferimento o cancellazione di un cambio piano programmato che non esiste
  • Messaggio: Nessun cambio piano programmato trovato per questo abbonamento.
• SUBSCRIPTION_EXPIRED
  • Trigger: Fatturazione oltre ends_at
  • Messaggio: Abbonamento scaduto impossibile creare nuovi addebiti
• SUBSCRIPTION_INACTIVE
  • Trigger: Stato ≠ ACTIVE
  • Messaggio: Abbonamento non attivo
• SUBSCRIPTION_NOT_ON_DEMAND
  • Trigger: Previsto su richiesta ma ottenuto intervallo fisso
  • Messaggio: L’abbonamento non è già su richiesta
• SUBSCRIPTION_PAYMENT_RETRY_LIMIT_EXCEEDED
  • Trigger: Tentativi di pagamento d’abbonamento ripetuti hanno superato il massimo numero di tentativi
  • Messaggio: Limite massimo di 10 tentativi superato per questo abbonamento

​

Prodotti, Carrello & Marchi

• BRAND_MISMATCH
  • Trigger: Gli articoli del carrello appartengono a marchi diversi
  • Messaggio: Tutti gli articoli nel carrello del prodotto devono appartenere allo stesso marchio
• BRAND_NOT_ENABLED
  • Trigger: Marchio è disabilitato o non attivo
  • Messaggio: Il marchio fornito non è abilitato
• BRAND_SUBMISSION_NOT_ENABLED
  • Trigger: Funzione di reinvio della verifica del marchio non abilitata
  • Messaggio: Il reinvio della verifica del marchio non è abilitato
• FILE_IN_USE
  • Trigger: Eliminazione di un file di prodotto digitale ancora riferito da concessioni di diritti attivi (passare ?force=true per ignorare)
  • Messaggio: File digitale è riferito da concessioni attive
• INVALID_SUGGESTED_PRICE
  • Trigger: Prezzo PWYW < prezzo minimo consentito
  • Messaggio: Il prezzo suggerito non può essere inferiore al prezzo minimo. In caso di paga quello che vuoi, il prezzo è considerato l’importo minimo accettato
• LOCALIZED_PRICE_ALREADY_EXISTS
  • Trigger: Esiste già un prezzo localizzato per questo prodotto e paese/valuta
  • Messaggio: Esiste già un prezzo localizzato per questo prodotto e paese/valuta
• LOCALIZED_PRICE_DUPLICATES_BASE
  • Trigger: Il prezzo localizzato duplica la valuta/paese base del prodotto
  • Messaggio: Il prezzo localizzato duplica la valuta/paese base del prodotto
• LOCALIZED_PRICE_SHAPE_MISMATCH
  • Trigger: La forma del prezzo localizzato non corrisponde all’pricing_mode del prodotto
  • Messaggio: La forma del prezzo localizzato non corrisponde al pricing_mode del prodotto
• MISSING_PRODUCT_INFORMATION
  • Trigger: Il prodotto esiste ma manca info obbligatorie
  • Messaggio: Prodotto esiste ma altre informazioni obbligatorie mancano o sono non valide
• PAY_AS_YOU_WANT_AMOUNT_REQUIRED
  • Trigger: Prezzo mancante per prodotto PWYW
  • Messaggio: L’importo è obbligatorio per il prodotto paga come vuoi
• PRODUCT_CART_EMTPY
  • Trigger: Carrello del prodotto vuoto inviato
  • Messaggio: il product_cart è vuoto (il codice di errore è intenzionalmente scritto EMTPY per corrispondere al valore esatto che l’API restituisce)
• PRODUCT_COLLECTION_IS_DELETED
  • Trigger: Operazione su una collezione di prodotti che è stata eliminata
  • Messaggio: Nessun messaggio
• PRODUCT_COLLECTION_MUST_HAVE_PRODUCTS
  • Trigger: Rimozione dell’ultimo prodotto (o ultimo gruppo con prodotti) da una collezione
  • Messaggio: Impossibile eliminare l’ultimo prodotto in una collezione. Archivia invece la collezione.
• PRODUCT_IS_DELETED
  • Trigger: Prodotto cancellato morbido
  • Messaggio: Nessun messaggio
• PRODUCT_PRICING_MODE_REQUIRED
  • Trigger: Aggiunta di prezzi localizzati prima che l’pricing_mode del prodotto sia impostato
  • Messaggio: Il pricing_mode del prodotto deve essere impostato prima di aggiungere prezzi localizzati
• SLUG_ALREADY_TAKEN
  • Trigger: Lo slug del prodotto richiesto / URL corto è già in uso
  • Messaggio: Lo slug è già preso
• UNABLE_TO_EDIT_PRIMARY_BRAND
  • Trigger: Tentativo di aggiornare il marchio primario tramite API regolare
  • Messaggio: Il marchio primario non può essere aggiornato tramite questo endpoint API.

​

Sconti

• DISCOUNT_ALREADY_USED_ON_SUBSCRIPTION
  • Trigger: Riapplicazione di uno sconto già utilizzato su questo abbonamento
  • Messaggio: Questo sconto è già stato utilizzato su questo abbonamento
• DISCOUNT_CODE_ALREADY_EXISTS
  • Trigger: Creazione di un codice sconto duplicato
  • Messaggio: Il Codice Sconto esiste già
• DISCOUNT_CODE_EXPIRED
  • Trigger: Codice sconto oltre la sua expires_at data
  • Messaggio: Codice sconto scaduto
• DISCOUNT_CODE_USAGE_LIMIT_EXCEEDED
  • Trigger: Sconto riutilizzato dopo usage_limit raggiunto
  • Messaggio: Il limite di utilizzo non può essere inferiore a times_used / Limite di utilizzo del codice sconto raggiunto
• DISCOUNT_NOT_APPLICABLE_TO_NEW_PRODUCT
  • Trigger: Cambio piano a un prodotto a cui lo sconto esistente non si applica
  • Messaggio: Lo sconto non è applicabile al prodotto del nuovo piano
• DISCOUNT_NOT_AVAILABLE_FOR_ON_DEMAND
  • Trigger: Codice applicato all’abbonamento su richiesta
  • Messaggio: Il coupon sconto non è disponibile per gli abbonamenti su richiesta
• DISCOUNT_NOT_AVAILABLE_FOR_PRODUCT
  • Trigger: Codice applicato a prodotto(i) non correlati
  • Messaggio: Il coupon sconto non è disponibile per questo prodotto
• INVALID_DISCOUNT_CODE
  • Trigger: Codice non esiste / non applicabile
  • Messaggio: Codice Sconto non valido / Codice Sconto non può essere applicato a nessun prodotto nel carrello
• INVALID_PERCENTAGE
  • Trigger: Importo percentuale > 100% (o 10.000 punti base)
  • Messaggio: L’importo percentuale non può essere superiore a 10000 / L’importo del codice sconto non può essere superiore al 100%
• UNSUPPORTED_DISCOUNT_TYPE
  • Trigger: Sconti a importo fisso, ecc., non ancora live
  • Messaggio: Attualmente sono supportati solo i codici sconto percentuale

​

Chiavi di Licenza

• ACTIVATION_LIMIT_LESS_THAN_CURRENT_AMOUNT
  • Trigger: Attivazioni di chiavi di licenza: nuovo limite < numero istanze esistenti
  • Messaggio: Il nuovo limite di attivazione non può essere inferiore al conteggio istanze corrente
• INACTIVE_LICENSE_KEY
  • Trigger: Stato chiave ≠ ACTIVE
  • Messaggio: La chiave di licenza non è attiva
• LICENSE_KEY_LIMIT_REACHED
  • Trigger: Attivazioni = limite
  • Messaggio: Limite di attivazione della chiave di licenza raggiunto
• LICENSE_KEY_NOT_FOUND
  • Trigger: ID istanza o ID chiave non valido
  • Messaggio: L’istanza della chiave di licenza non è trovata o non appartiene a questa chiave di licenza
• NO_EXPIRY_ON_SUBSCRIPTION_LICENSE_KEYS
  • Trigger: Tentativo di impostare la scadenza su chiave basata su abbonamento
  • Messaggio: Impossibile impostare la data di scadenza per la chiave di licenza basata su abbonamento

​

Fatturazione Basata sull’Uso & Metering

• DUPLICATE_METER_IDS_IN_REQUEST
  • Trigger: Lo stesso ID meter appare più volte nella richiesta
  • Messaggio: Gli ID meter duplicati non sono consentiti
• INVALID_QUANTITY
  • Trigger: Quantità non valida specificata per prezzi basati sull’uso
  • Messaggio: Solo 1 quantità consentita nei prodotti prezzo basato sull’uso
• METER_IS_DELETED
  • Trigger: Tentativo di utilizzo di un meter eliminato
  • Messaggio: Il Meter è già stato eliminato
• MISSING_METER_IDS
  • Trigger: Lista ID meter vuota o contiene ID non validi
  • Messaggio: Uno o più ID meter non esistono:

​

Fatturazione Basata su Crediti

• CREDIT_ENTITLEMENT_IS_DELETED
  • Trigger: Operazione su un diritto di credito che è stato eliminato
  • Messaggio: Il diritto di credito è già stato eliminato
• CREDIT_ENTITLEMENT_NAME_ALREADY_EXISTS
  • Trigger: Creazione di un diritto di credito con un nome già esistente
  • Messaggio: Esiste già un diritto di credito con questo nome
• OVERAGE_LIMIT_EXCEEDED
  • Trigger: Un uso o una deduzione di credito supererebbe il limite di overage configurato
  • Messaggio: Limite di overage superato

​

Portafoglio

• INSUFFICIENT_WALLET_FUNDS
  • Trigger: Saldo del portafoglio < importo di debito
  • Messaggio: Fondi insufficienti nel portafoglio
• NEGATIVE_BALANCE_ADJUSTMENT
  • Trigger: Tentativo di rendere negativo il saldo del portafoglio
  • Messaggio: Il saldo del portafoglio non può essere reso negativo

​

Valuta, Tassa & Regione

• EXCHANGE_RATE_NOT_FOUND
  • Trigger: Nessun tasso di cambio per la coppia valutaria from → to
  • Messaggio: Tasso di cambio non trovato per convertire da Valuta a Valuta
• INVALID_TAX_ID
  • Trigger: Validazione fallita di IVA/GST/TIN
  • Messaggio: ID fiscale non valido
• REQUEST_AMOUNT_BELOW_MINIMUM
  • Trigger: Importo < minimo del prodotto
  • Messaggio: L’importo non può essere inferiore all’importo minimo specificato per il prodotto
• TOTAL_PAYMENT_AMOUNT_BELOW_MINIMUM_AMOUNT
  • Trigger: Totale combinato del carrello < minimo del gateway
  • Messaggio: È richiesto un importo minimo di per elaborare il pagamento
• UNSUPPORTED_BILLING_CURRENCY
  • Trigger: Gli abbonamenti sono limitati all’USD
  • Messaggio: La valuta di fatturazione non in USD non è supportata per gli abbonamenti
• UNSUPPORTED_COUNTRY
  • Trigger: Geo non ancora supportato
  • Messaggio: Paese attualmente non supportato
• UNSUPPORTED_CURRENCY
  • Trigger: Valuta del prodotto o dell’add-on non valida
  • Messaggio: La valuta non è attualmente supportata / Solo prodotti in USD e INR attualmente supportati / Solo USD e INR supportati per il prezzo dell’add-on / Si può richiedere solo USD o INR per la billing_currency / Valuta Non Supportata / Valuta inaspettata per abbonamenti con carta indiana
• UNSUPPORTED_TAX_CATEGORY
  • Trigger: Stringa della categoria fiscale non nell’enum
  • Messaggio: La categoria attualmente non è supportata

​

Validazione & Richieste

• DUPLICATE_LINE_ITEMS_IN_REQUEST
  • Trigger: Lo stesso item_id appare due volte in items[]
  • Messaggio: Gli item_ids duplicati specificati nell’array degli articoli
• INVALID_QUERY_PARAMS
  • Trigger: Parametri di query mutuamente esclusivi / malformati
  • Messaggio: I parametri di query devono contenere solo il time_frame o (start, end)
• INVALID_REQUEST_BODY
  • Trigger: JSON malformato o violazione dello schema
  • Messaggio: Il tuo corpo di richiesta è invalido. Si prega di controllare le intestazioni della richiesta e l’oggetto.
• INVALID_REQUEST_PARAMETERS
  • Trigger: Semantica errata (es. data nel passato)
  • Messaggio: Impossibile cambiare next_billing_date a tempo passato
• MAXIMUM_KEYS_REACHED
  • Trigger: Metadati / campi personalizzati superano 50 coppie
  • Messaggio: Supera le 50 coppie chiave-valore

​

Generale & Sistema

• INTEGER_CONVERSION_FAILURE
  • Trigger: Qualsiasi conversione integer ↔ string/decimal che fallisce lato server
  • Messaggio: Fallimento Conversione Integer
• INTERNAL_SERVER_ERROR
  • Trigger: Eccezioni non gestite; devi registrare i dettagli lato server
  • Messaggio: Nessun messaggio pubblico (generico 500)
• NOT_FOUND
  • Trigger: Generico 404 per qualsiasi risorsa mancante
  • Messaggio: Elemento non trovato (o più specifico)
• TOO_MANY_REQUESTS
  • Trigger: Limite di frequenza 429
  • Messaggio: Nessun messaggio
• UNSUPPORTED_ACTION
  • Trigger: Azione non supportata per il tipo di risorsa
  • Messaggio: Cambiare piani per gli abbonamenti basati sull’uso non è supportato

​

Migliori Pratiche

1. Gestisci sempre gli errori con grazia nella tua applicazione
2. Implementa un corretto logging degli errori
3. Usa messaggi di errore appropriati per gli utenti finali
4. Implementa la logica di ritentativo per errori transitori
5. Contatta il supporto per problemi non risolti

​

Supporto