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

• ACTIVATION_LIMIT_LESS_THAN_CURRENT_AMOUNT
  • Attivazione: Attivazioni della chiave di licenza: nuovo limite < conteggio delle istanze esistenti
  • Messaggio: Il nuovo limite di attivazione non può essere inferiore al conteggio delle istanze attuali
• ADDONS_IN_USAGE_BASED_BILLING_NOT_SUPPORTED
  • Attivazione: Tentativo di aggiungere addon a sottoscrizioni basate sull’uso
  • Messaggio: Gli addon nelle sottoscrizioni non sono supportati per la fatturazione basata sull’uso
• ADDONS_NOT_ALLOWED_FOR_ON_DEMAND
  • Attivazione: Tentativo di aggiungere addon a sottoscrizioni on-demand
  • Messaggio: Gli addon non sono consentiti per le sottoscrizioni on-demand
• BRAND_MISMATCH
  • Attivazione: Gli articoli del carrello appartengono a marchi diversi
  • Messaggio: Tutti gli articoli nel carrello dei prodotti devono appartenere allo stesso marchio
• BRAND_NOT_ENABLED
  • Attivazione: Il marchio è disabilitato o non attivo
  • Messaggio: Il marchio fornito non è abilitato
• BRAND_SUBMISSION_NOT_ENABLED
  • Attivazione: La funzionalità di reinvio della verifica del marchio non è abilitata
  • Messaggio: Il reinvio della verifica del marchio non è abilitato
• CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • Attivazione: Tentativo di addebitare una sottoscrizione programmata per la cancellazione
  • Messaggio: Sottoscrizione programmata per la cancellazione
• CHECKOUT_SESSION_CONSUMED
  • Attivazione: La sessione di checkout ha già generato un pagamento
  • Messaggio: La sessione di checkout è già stata consumata
• DISCOUNT_CODE_ALREADY_EXISTS
  • Attivazione: Creazione di un codice sconto duplicato
  • Messaggio: Il codice sconto esiste già
• DISCOUNT_CODE_EXPIRED
  • Attivazione: Il codice sconto è scaduto il expires_at
  • Messaggio: Il codice sconto è scaduto
• DISCOUNT_CODE_USAGE_LIMIT_EXCEEDED
  • Attivazione: Codice sconto riutilizzato dopo che usage_limit è stato raggiunto
  • Messaggio: Il limite di utilizzo non può essere inferiore a times_used / Il codice sconto ha raggiunto il limite di utilizzo
• DISCOUNT_NOT_AVAILABLE_FOR_ON_DEMAND
  • Attivazione: Codice applicato a sottoscrizione on-demand
  • Messaggio: Il coupon sconto non è disponibile per le sottoscrizioni on-demand
• DISCOUNT_NOT_AVAILABLE_FOR_PRODUCT
  • Attivazione: Codice applicato a prodotto/i non correlati
  • Messaggio: Il coupon sconto non è disponibile per questo prodotto
• DUPLICATE_LINE_ITEMS_IN_REQUEST
  • Attivazione: Lo stesso item_id appare due volte in items[]
  • Messaggio: ID articolo duplicati specificati nell’array degli articoli
• DUPLICATE_METER_IDS_IN_REQUEST
  • Attivazione: Lo stesso ID del misuratore appare più volte nella richiesta
  • Messaggio: ID del misuratore duplicati non sono consentiti
• EXCHANGE_RATE_NOT_FOUND
  • Attivazione: Nessun tasso FX per la coppia di valute from → to
  • Messaggio: Tasso di cambio non trovato per convertire da Valuta a Valuta
• EXISTING_REFUND_REQUEST_PROCESSING
  • Attivazione: La richiesta di rimborso precedente è ancora in fase di elaborazione
  • Messaggio: Una richiesta di rimborso con stato “In attesa” è ancora in fase di elaborazione
• INACTIVE_LICENSE_KEY
  • Attivazione: Stato della chiave ≠ ACTIVE
  • Messaggio: La chiave di licenza non è attiva
• INACTIVE_SUBSCRIPTION_PLAN_CHANGE_NOT_SUPPORTED
  • Attivazione: Modifica del piano su sottoscrizione inattiva
  • Messaggio: Cambiare piano non è supportato per sottoscrizioni inattive
• INSUFFICIENT_WALLET_FUNDS
  • Attivazione: Saldo del portafoglio < importo di addebito
  • Messaggio: Fondi insufficienti nel portafoglio
• INTEGER_CONVERSION_FAILURE
  • Attivazione: Qualsiasi conversione intera ↔ stringa/decimale che fallisce lato server
  • Messaggio: Errore di conversione intera
• INTERNAL_SERVER_ERROR
  • Attivazione: Eccezioni non gestite; dovresti registrare i dettagli lato server
  • Messaggio: Nessun messaggio pubblico (generico 500)
• INVALID_DISCOUNT_CODE
  • Attivazione: Il codice non esiste / non applicabile
  • Messaggio: Codice sconto non valido / Il codice sconto non può essere applicato a nessun prodotto nel carrello
• INVALID_PERCENTAGE
  • Attivazione: 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%
• INVALID_QUANTITY
  • Attivazione: Quantità non valida specificata per la fatturazione basata sull’uso
  • Messaggio: Solo 1 quantità consentita nei prodotti a prezzo basato sull’uso
• INVALID_QUERY_PARAMS
  • Attivazione: Parametri di query mutualmente esclusivi / malformati
  • Messaggio: I parametri di query devono contenere solo time_frame o (start, end)
• INVALID_REQUEST_BODY
  • Attivazione: JSON malformato o violazione dello schema
  • Messaggio: Il corpo della tua richiesta non è valido. Controlla le intestazioni della richiesta e l’oggetto.
• INVALID_REQUEST_PARAMETERS
  • Attivazione: Semantica errata (ad es. data nel passato)
  • Messaggio: Impossibile cambiare next_billing_date a un tempo passato
• INVALID_SUGGESTED_PRICE
  • Attivazione: Prezzo PWYW < prezzo minimo consentito
  • Messaggio: Il prezzo suggerito non può essere inferiore al prezzo minimo. In caso di paga quanto vuoi, il prezzo è considerato come importo minimo accettato
• INVALID_TAX_ID
  • Attivazione: Validazione fallita di VAT/GST/TIN
  • Messaggio: L’ID fiscale non è valido
• LICENSE_KEY_LIMIT_REACHED
  • Attivazione: Attivazioni = limite
  • Messaggio: Limite di attivazione della chiave di licenza raggiunto
• LICENSE_KEY_NOT_FOUND
  • Attivazione: ID dell’istanza o ID della chiave non valido
  • Messaggio: L’istanza della chiave di licenza non è stata trovata o non appartiene a questa chiave di licenza
• LINE_ITEM_FULLY_REFUNDED
  • Attivazione: Tentativo di rimborsare un articolo già completamente rimborsato
  • Messaggio: L’articolo è stato completamente rimborsato e non può essere ulteriormente rimborsato.
• LINE_ITEM_NOT_FOUND
  • Attivazione: ID articolo non parte del pagamento di riferimento
  • Messaggio: L’articolo non è stato trovato nel pagamento
• LINE_ITEM_PRORATED
  • Attivazione: Tentativo di rimborso o aggiornamento su una linea prorata
  • Messaggio: L’articolo non può essere rimborsato perché è prorata
• LINE_ITEM_REFUND_AMOUNT_TOO_HIGH
  • Attivazione: Importo del rimborso > importo pagato (tasse incl.)
  • Messaggio: L’importo richiesto per il rimborso dell’articolo incluso le tasse è che supera l’importo pagato
• LINE_ITEM_REFUND_AMOUNT_TOO_LOW
  • Attivazione: Importo del rimborso al di sotto della soglia minima
  • Messaggio: L’importo richiesto per il rimborso dell’articolo è che è troppo basso
• MAXIMUM_KEYS_REACHED
  • Attivazione: Metadata / campi personalizzati superati 50 coppie
  • Messaggio: Supera 50 coppie chiave-valore
• MERCHANT_NOT_LIVE
  • Attivazione: L’attività è ancora in modalità test/sandbox
  • Messaggio: Il commerciante non è attivo
• METER_IS_DELETED
  • Attivazione: Tentativo di utilizzare un misuratore eliminato
  • Messaggio: Il misuratore è già stato eliminato
• MISSING_ADDON_IDS
  • Attivazione: addon_id lista vuota o ID sconosciuti
  • Messaggio: Uno o più ID prodotto non esistono:
• MISSING_METER_IDS
  • Attivazione: Lista ID misuratore vuota o contiene ID non validi
  • Messaggio: Uno o più ID misuratore non esistono:
• MISSING_PRODUCT_INFORMATION
  • Attivazione: Il prodotto esiste ma manca informazioni obbligatorie
  • Messaggio: Il prodotto esiste ma altre informazioni obbligatorie sono mancanti o non valide
• NEGATIVE_BALANCE_ADJUSTMENT
  • Attivazione: Tentativo di rendere negativo il saldo del portafoglio
  • Messaggio: Non è consentito rendere negativo il saldo del portafoglio
• NO_ELIGIBLE_PAYMENT_METHODS
  • Attivazione: Dopo il filtraggio, non è rimasto nulla
  • Messaggio: Nessun metodo di pagamento idoneo trovato
• NO_EXPIRY_ON_SUBSCRIPTION_LICENSE_KEYS
  • Attivazione: Tentativo di impostare la scadenza su chiave basata su sottoscrizione
  • Messaggio: Non è possibile impostare la data di scadenza per la chiave di licenza basata su sottoscrizione
• NOT_FOUND
  • Attivazione: 404 generico per qualsiasi risorsa mancante
  • Messaggio: Articolo non trovato (o più specifico)
• ON_DEMAND_PLAN_CHANGE_NOT_SUPPORTED
  • Attivazione: Cambio piano non consentito per on-demand
  • Messaggio: Cambiare piano non è supportato per sottoscrizioni on-demand
• ON_DEMAND_SUBSCRIPTIONS_NOT_ENABLED
  • Attivazione: L’attività ha il flag funzionalità disattivato
  • Messaggio: Le sottoscrizioni on-demand non sono abilitate per questa attività
• ON_DEMAND_USAGE_BASED_BILLING_NOT_SUPPORTED
  • Attivazione: Tentativo di utilizzare on-demand con fatturazione basata sull’uso
  • Messaggio: Le sottoscrizioni on-demand non sono supportate per la fatturazione basata sull’uso
• PAY_AS_YOU_WANT_AMOUNT_REQUIRED
  • Attivazione: Prezzo mancante per prodotto PWYW
  • Messaggio: L’importo è obbligatorio per il prodotto paga quanto vuoi
• PAYMENT_ALREADY_REFUNDED
  • Attivazione: Rimborso duplicato
  • Messaggio: Questo pagamento è già stato rimborsato
• PAYMENT_HAS_BEEN_REFUNDED
  • Attivazione: Il pagamento è stato completamente rimborsato
  • Messaggio: L’ID di pagamento è stato completamente rimborsato.
• PAYMENT_NOT_SUCCEEDED
  • Attivazione: Tentativo di rimborsare/processare un pagamento non riuscito
  • Messaggio: Il pagamento fornito non è andato a buon fine
• PLAN_CHANGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • Attivazione: Modifica del piano tentata su sottoscrizione programmata per la cancellazione
  • Messaggio: Sottoscrizione programmata per la cancellazione
• PREVIOUS_PAYMENT_PENDING
  • Attivazione: Tentativo di creare un addebito mentre il precedente è in uno stato non terminale
  • Messaggio: Non è possibile creare un nuovo addebito poiché il pagamento precedente non è ancora andato a buon fine
• PRODUCT_CART_EMPTY
  • Attivazione: Carrello dei prodotti vuoto inviato
  • Messaggio: carrello_prodotti è vuoto
• PRODUCT_IS_DELETED
  • Attivazione: Prodotto eliminato soft
  • Messaggio: Nessun messaggio
• REFUND_AMOUNT_EXCEEDS_PAID_AMOUNT
  • Attivazione: L’importo totale del rimborso aggregato > importo pagato
  • Messaggio: L’importo di rimborso calcolato è maggiore dell’importo pagato
• REFUND_WINDOW_EXPIRED
  • Attivazione: Fuori dalla finestra di rimborso consentita
  • Messaggio: I rimborsi non possono essere avviati giorni dopo la creazione del pagamento. Contatta [email protected].
• REQUEST_AMOUNT_BELOW_MINIMUM
  • Attivazione: Importo < minimo prodotto
  • Messaggio: L’importo non può essere inferiore all’importo minimo specificato per il prodotto
• SUBSCRIPTION_EXPIRED
  • Attivazione: Fatturazione oltre ends_at
  • Messaggio: Sottoscrizione scaduta, non è possibile creare nuovi addebiti
• SUBSCRIPTION_INACTIVE
  • Attivazione: Stato ≠ ACTIVE
  • Messaggio: La sottoscrizione non è attiva
• SUBSCRIPTION_NOT_ON_DEMAND
  • Attivazione: Atteso on-demand ma ottenuto intervallo fisso
  • Messaggio: La sottoscrizione non è già on-demand
• SUBSCRIPTION_PAYMENT_RETRY_LIMIT_EXCEEDED
  • Attivazione: I tentativi di pagamento della sottoscrizione hanno superato il numero massimo di tentativi
  • Messaggio: Limite massimo di tentativi di 10 superato per questa sottoscrizione
• TOO_MANY_REQUESTS
  • Attivazione: Limite di frequenza 429
  • Messaggio: Nessun messaggio
• TOTAL_PAYMENT_AMOUNT_BELOW_MINIMUM_AMOUNT
  • Attivazione: Totale del carrello combinato < minimo del gateway
  • Messaggio: È richiesto un importo minimo di per elaborare il pagamento
• UNABLE_TO_EDIT_PRIMARY_BRAND
  • Attivazione: Tentativo di aggiornare il marchio principale tramite API regolare
  • Messaggio: Il marchio principale non può essere aggiornato tramite questo endpoint API.
• UNAUTHORIZED
  • Attivazione: Nessuna chiave API o token/scopo non valido
  • Messaggio: Non sei autorizzato a eseguire questa azione
• UNSUPPORTED_ACTION
  • Attivazione: Azione non supportata per tipo di risorsa
  • Messaggio: Cambiare piano per sottoscrizioni basate sull’uso non è supportato
• UNSUPPORTED_BILLING_CURRENCY
  • Attivazione: Sottoscrizioni limitate a USD
  • Messaggio: La valuta di fatturazione non USD non è supportata per le sottoscrizioni
• UNSUPPORTED_COUNTRY
  • Attivazione: Geo non ancora supportato
  • Messaggio: Paese attualmente non supportato
• UNSUPPORTED_CURRENCY
  • Attivazione: Valuta del prodotto o addon non valida
  • Messaggio: La valuta non è attualmente supportata / Solo prodotti USD e INR supportati attualmente / Solo USD e INR supportati per il prezzo dell’addon / È possibile richiedere solo USD o INR per la valuta di fatturazione / Valuta non supportata / Valuta imprevista per le sottoscrizioni con carta indiana
• UNSUPPORTED_DISCOUNT_TYPE
  • Attivazione: Sconti a importo fisso, ecc., non ancora attivi
  • Messaggio: Solo codici sconto percentuali sono supportati per ora
• UNSUPPORTED_PAYMENT_CURRENCY
  • Attivazione: Valuta di pagamento bloccata per il connettore
  • Messaggio: La transazione INR non è supportata per questa transazione
• UNSUPPORTED_TAX_CATEGORY
  • Attivazione: La stringa della categoria fiscale non è nell’enum
  • Messaggio: Categoria attualmente non supportata
• UNSUCCESSFUL_PAYMENT_ID
  • Attivazione: L’ID di pagamento fa riferimento a un pagamento non riuscito
  • Messaggio: L’ID di pagamento ha uno stato non riuscito.
• ZERO_AMOUNT_PAYMENT_REFUND_NOT_ALLOWED
  • Attivazione: Tentativo di rimborsare un pagamento di zero importo
  • Messaggio: Non è possibile rimborsare un pagamento con importo di valuta zero

​

Migliori Pratiche

1. Gestisci sempre gli errori in modo elegante nella tua applicazione
2. Implementa una corretta registrazione degli errori
3. Usa messaggi di errore appropriati per gli utenti finali
4. Implementa la logica di ripetizione per errori transitori
5. Contatta il supporto per problemi irrisolti

​

Supporto