Passa al contenuto
Crea account
 o
Accedi
Il logo della documentazione Stripe
/
Crea un account
Accedi

Gestione degli errori

Rilevare o rispondere a rifiuti, dati non validi, problemi di rete e molto altro ancora

Copia pagina

Stripe offre svariate tipologie di errori, i quali possono rappresentare eventi esterni, come i pagamenti rifiutati e le interruzioni di rete, oppure problemi legati al codice, come le chiamate API non valide.

Per gestire gli errori, usa alcune delle o tutte le tecniche riportate nella tabella che segue. Indipendentemente dalla tecnica che scegli, puoi monitorare la situazione con le nostre risposte consigliate per ciascun tipo di errore.

TecnicaScopoQuando è necessario
Rilevare le eccezioniRipristino se una chiamata API non può proseguireSempre
Monitorare i webhookReazione alle notifiche da StripeA volte
Ottenere informazioni salvate sugli erroriAnalisi di problemi passati e supporto di altre tecnicheA volte

Rilevare le eccezioni

Se un problema immediato impedisce a una chiamata API di continuare, la libreria Node.js di Stripe può generare un’eccezione. È consigliabile sollevare e gestire le eccezioni. Per abilitare questa funzionalità, eseguire le operazioni seguenti:

  • Se effettui la chiamata API in una funzione, anteponi la parola chiave async alla definizione della funzione.
  • Anteponi la parola chiave await alla stessa chiamata API.
  • Inserisci la chiamata API in un blocco try/catch.

Quando rilevi un’eccezione, puoi usare il suo attributo Tipo per scegliere una risposta.

const stripe = require('stripe')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

async function exampleFunction(args) {
  try {
    const paymentIntent = await stripe.paymentIntents.create(args);
    console.log('No error.');
  } catch (e) {
    switch (e.type) {
      case 'StripeCardError':
        console.log(`A payment error occurred: ${e.message}`);
        break;
      case 'StripeInvalidRequestError':
        console.log('An invalid request occurred.');
        break;
      default:
        console.log('Another problem occurred, maybe unrelated to Stripe.');
        break;
    }
  }
}

Dopo aver configurato la gestione delle eccezioni, testala con dati diversi, tra cui le carte di test, per simulare diversi esiti di pagamento.

exampleFunction({
  // The required parameter currency is missing
  amount: 2000,
  confirm: true,
  payment_method: 
'pm_card_visa'
,
})
console
An invalid request occurred.

Monitorare i webhook

Stripe utilizza i webhook per informarti in merito a svariate tipologie di problemi, tra cui quelli che non seguono immediatamente le chiamate API. Ad esempio:

  • Perdi una contestazione.
  • Un pagamento ricorrente dà esito negativo dopo mesi di esiti positivi.
  • Il tuo front-end conferma un pagamento ma va offline prima di scoprire che il pagamento non è andato a buon fine (il back-end riceve comunque la notifica del webhook, anche se non è stato lui a effettuare la chiamata API).

Non occorre che tu gestisca ogni tipo di evento webhook. Infatti, alcune integrazioni non li gestiscono affatto.

Nel tuo gestore di webhook, inizia dai passagggi base previsti nello sviluppatore dei webhook: ottieni un oggetto evento e usa il tipo di evento per scoprire cos’è successo. Quindi, se il tipo di evento indica un errore, attieniti a questi ulteriori passaggi:

  1. Accedi a event.data.object per recuperare l’oggetto interessato.
  2. Usa le informazioni salvate sull’oggetto interessato per capirne il contesto, compreso un oggetto errore.
  3. Usa il suo tipo per scegliere una risposta.
const stripe = require('stripe')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);
const express = require('express');
const app = express();

app.post('/webhook', express.json({type: 'application/json'}), (request, response) => {

  // Get an event object
  const event = request.body;

  // Use its type to find out what happened
  if (event.type == 'payment_intent.payment_failed') {

    // Get the object affected
    const paymentIntent = event.data.object;

    // Use stored information to get an error object
    const error = paymentIntent.last_payment_error;

    // Use its type to choose a response
    switch (error.type) {
      case 'card_error':
        console.log(`A payment error occurred: ${error.message}`);
        break;
      case 'invalid_request_error':
        console.log('An invalid request occurred.');
        if (error.param) {
          console.log(`The parameter ${error.param} is invalid or missing.`);
        }
        break;
      default:
        console.log('Another problem occurred, maybe unrelated to Stripe.');
        break;
    }
  }
  response.send();
});

app.listen(4242, () => console.log('Running on port 4242'));

Per testare il modo in cui l’integrazione risponde agli eventi webhook, puoi attivare eventi webhook in locale. Una volta completata la procedura di configurazione a quel link, attiva un pagamento non riuscito per vedere il messaggio di errore che ne risulta.

Command Line
stripe trigger payment_intent.payment_failed
Output
A payment error occurred: Your card was declined.

Ottenere informazioni salvate sugli errori

Molti oggetti salvano informazioni sugli errori. Ciò significa che, se qualcosa era già andato storto, puoi recuperare l’oggetto ed esaminarlo per saperne di più. In molti casi, le informazioni salvate hanno la forma di un oggetto errore, e potrai usarne il tipo per scegliere una risposta.

Ad esempio:

  1. Recuperare un Payment Intent specifico.
  2. Controllare se si è verificato un errore legato al pagamento determinando se il campo last_payment_error è vuoto.
  3. Se si è verificato, registrare l’errore, compreso il tipo e l’oggetto interessato.
const stripe = require('stripe')(
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

const payment_intent = await stripe.paymentIntents.retrieve(
'{{PAYMENT_INTENT_ID}}'
)

const e = payment_intent.last_payment_error

if (e !== null) {
  console.log(`PaymentIntent ${payment_intent.id} experienced a ${e.type} error.`)
}

Ecco alcuni oggetti comuni che salvano informazioni sugli errori.

OggettoAttributoValori
Payment Intentlast_payment_errorUn oggetto errore
Setup Intentlast_setup_errorUn oggetto errore
Fatturalast_finalization_errorUn oggetto errore
Setup Attemptsetup_errorUn oggetto errore
Payoutfailure_codeUn codice di bonifico non riuscito
Rimborsofailure_reasonUn codice di rimborso non riuscito

Per testare il codice che utilizza le informazioni salvate sugli errori, spesso è necessario simulare le transazioni non riuscite. Per farlo, nella gran parte dei casi puoi utilizzare le carte di test o i numeri di conto bancario di test. Ad esempio:

Tipi di errori e risposte

Nella libreria Node.js di Stripe, ogni oggetto errore ha un attributo type. Leggi la documentazione relativa a ciascun tipo per sapere come rispondere.

Nome

Tipo

Descrizione
Errore legato al pagamento

StripeCardError

Si è verificato un errore durante un pagamento, che riguarda una delle seguenti situazioni:
Errore di richiesta non valida

StripeInvalidRequestError

Hai effettuato una chiamata API con parametri errati, nello stato errato o in un modo non valido.

Errore di connessione

StripeConnectionError

Si è verificato un problema di rete tra il tuo server e Stripe.
Errore API

StripeAPIError

Si è verificato un problema lato Stripe (questi casi sono rari).
Errore di autenticazione

StripeAuthenticationError

Stripe non può autenticarti con le informazioni fornite.
Errore di idempotenza

StripeIdempotencyError

Hai usato una chiave di idempotenza per qualcosa di imprevisto, come la ripetizione di una richiesta ma specificando parametri diversi.
Errore di autorizzazione

StripePermissionError

La chiave API utilizzata per questa richiesta non dispone delle autorizzazioni necessarie.
Errore di limitazione della velocità

StripeRateLimitError

Hai effettuato troppe chiamate API in troppo poco tempo.
Errore di verifica di firma

StripeSignatureVerificationError

Stai usando la verifica della firma del webhook e non abbiamo potuto verificare l’autenticità di un evento webhook.

Errori legati al pagamento

Gli errori legati al pagamento (a volte definiti anche “errori carte” per motivi storici) abbracciano un’ampia gamma di problemi comuni, suddivisibili in tre categorie:

Per distinguere queste categorie o per ottenere maggiori informazioni su come rispondere, verifica il codice di errore, il codice di rifiuto e l’esito dell’addebito.

(Per trovare l’esito dell’addebito a partire da un oggetto errore, individua prima il Payment Intent coinvolto e l’ultimo addebito che ha creato. Vedi l’esempio che segue per una dimostrazione.)

const stripe = require('stripe')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

async function exampleFunction(args) {
    try {
      const paymentIntent = await stripe.paymentIntents.create(args);
    } catch (e) {
      console.log(e)
      const charge = await stripe.charges.retrieve(e.payment_intent.latest_charge)
      if (e.type === 'StripeCardError') {
        if (charge.outcome.type === 'blocked') {
          console.log('Payment blocked for suspected fraud.')
        } else if (e.code === 'card_declined') {
          console.log('Payment declined by the issuer.')
        } else if (e.code === 'expired_card') {
          console.log('Card expired.')
        } else {
          console.log('Other card error.')
        }
      }
    }
  }

Utenti con versione API 2022-08-01 o precedente:

(Per trovare l’esito dell’addebito a partire da un oggetto errore, individua prima il Payment Intent coinvolto e l’ultimo addebito che ha creato. Vedi l’esempio che segue per una dimostrazione.)

const stripe = require('stripe')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

async function exampleFunction(args) {
    try {
      const paymentIntent = await stripe.paymentIntents.create(args);
    } catch (e) {
      console.log(e)
      if (e.type === 'StripeCardError') {
        if (e.payment_intent.charges.data[0].outcome.type === 'blocked') {
          console.log('Payment blocked for suspected fraud.')
        } else if (e.code === 'card_declined') {
          console.log('Payment declined by the issuer.')
        } else if (e.code === 'expired_card') {
          console.log('Card expired.')
        } else {
          console.log('Other card error.')
        }
      }
    }
  }

Puoi attivare alcuni tipi comuni di errori legati al pagamento con le carte di test. Consulta questi elenchi di opzioni:

Il codice di test che segue mostra alcune possibilità.

exampleFunction({
  currency: 'usd',
  amount: 2000,
  confirm: true,
  payment_method: 
'pm_card_radarBlock'
,
})
console
Payment blocked for suspected fraud.

Pagamento bloccato per sospetta frode

Tipo

StripeCardError

Codici
const charge = await stripe.charges.retrieve(e.payment_intent.latest_charge)
charge.outcome.type === 'blocked'
Codici

e.payment_intent.charges.data[0].outcome.type === 'blocked'

ProblemaIl sistema di prevenzione delle frodi di Stripe, Radar, ha bloccato il pagamento

Soluzioni

Questo errore può verificarsi quando l’integrazione funziona correttamente. Rilevalo e suggerisci al cliente una modalità di pagamento diversa.

Per bloccare un numero inferiore di pagamenti legittimi, prova queste soluzioni:

I clienti che usano Radar for Fraud Teams hanno a disposizione queste opzioni aggiuntive:

  • Per esentare un pagamento in particolare, aggiungilo al tuo elenco di consenso. Radar for Fraud Teams
  • Per modificare la tolleranza al rischio, regola le tue impostazioni di rischio. Radar for Fraud Teams
  • Per modificare i criteri per bloccare un pagamento, usa le regole personalizzate. Radar for Fraud Teams

Puoi testare le impostazioni della tua integrazione con le carte di test che simulano le frodi. Se utilizzi regole Radar personalizzate, segui i consigli sui test contenuti nella documentazione di Radar.

Pagamento rifiutato dalla società emittente

Tipo

StripeCardError

Codici

e.code === 'card_declined'

ProblemaLa società emittente della carta ha rifiutato il pagamento.

Soluzioni

Questo errore può verificarsi quando l’integrazione funziona correttamente. Riflette un’azione della società emittente, che potrebbe essere legittima. Usa il codice di rifiuto per stabilire quali siano i passaggi successivi più appropriati. Consulta la documentazione sui codici di rifiuto per sapere come rispondere in modo appropriato a ciascun codice.

Puoi anche:

Verifica il modo in cui la tua integrazione gestisce i rifiuti con le carte di test che simulano pagamenti andati a buon fine e rifiutati.

Altri errori legati al pagamento

Tipo

StripeCardError

ProblemaSi è verificato un altro errore legato al pagamento.
SoluzioniQuesto errore può verificarsi quando l’integrazione funziona correttamente. Usa il codice di errore per stabilire quali siano i passaggi successivi più appropriati. Consulta la documentazione sui codici di errore per sapere come rispondere in modo appropriato a ciascun codice.

Errori di richiesta non valida

Tipo

StripeInvalidRequestError

ProblemaHai effettuato una chiamata API con parametri errati, nello stato errato o in un modo non valido.
SoluzioniNella maggior parte dei casi, il problema riguarda la richiesta stessa: i suoi parametri non sono validi oppure non può essere effettuata nello stato attuale in cui si trova la tua integrazione.
  • Consulta la documentazione sui codici di errore per ulteriori informazioni sul problema.
  • Per comodità, segui il link a e.doc_url in cui troverai della documentazione sul codice di errore.
  • Se l’errore riguarda un parametro specifico, usa e.param per stabilire quale.

Errori di connessione

Tipo

StripeAPIConnectionError

ProblemaSi è verificato un problema di rete tra il tuo server e Stripe.

Soluzioni

Tratta il risultato della chiamata API come indeterminato. Cioè, non dare per scontato che sia andato o meno a buon fine.

Per verificare se ha avuto esito positivo, puoi:

  • Recuperare l’oggetto pertinente da Stripe e verificarne lo stato.
  • Ascoltare la notifica del webhook che indica se l’operazione ha avuto esito positivo o negativo.

Per aiutare a risolvere gli errori di connessione, puoi:

  • Quando crei o aggiorni un oggetto, utilizza una chiave di idempotenza. Poi, se si verifica un errore di connessione, puoi ripetere tranquillamente la richiesta senza il rischio di creare un secondo oggetto o di eseguire l’aggiornamento due volte. Ripeti la richiesta con la stessa chiave di idempotenza fino a quando non riceverai un esito positivo o negativo chiaro. Per informazioni dettagliate su questa strategia, consulta Gestione degli errori di basso livello.
  • Attivare la ripetizione automatica dei tentativi. Quindi, Stripe genera per te le chiavi di idempotenza e ripete le richieste quando è sicuro farlo.

Questo errore può celarne altri, per cui è possibile che una volta risolto l’errore di connessione, ne compaiano altri. Verifica la presenza di errori in tutte queste soluzioni, proprio come faresti nella richiesta originale.

Errori API

Tipo

StripeAPIError

ProblemaSi è verificato un problema lato Stripe (questi casi sono rari).

Soluzioni

Tratta il risultato della chiamata API come indeterminato, ovvero non supporre che abbia avuto esito positivo o negativo.

Usa i webhook per ricavare informazioni sull’esito. Quando possibile, Stripe genera dei webhook per tutti gli oggetti nuovi creati man mano che risolviamo un problema.

Affinché la tua integrazione sia il più robusta possibile in situazioni insolite, consulta questa discussione avanzata sugli errori del server.

Errori di autenticazione

Tipo

StripeAutheticationError

ProblemaStripe non può autenticarti con le informazioni fornite.
Soluzioni

Errori di idempotenza

Tipo

StripeIdempotencyError

ProblemaHai usato una chiave di idempotenza per qualcosa di imprevisto, come la ripetizione di una richiesta ma specificando parametri diversi.
Soluzioni
  • Una volta utilizzata, la chiave di idempotenza può essere riutilizzata per chiamate API identiche.
  • Usa chiavi di idempotenza inferiori a 255 caratteri.

Errori di autorizzazione

Tipo

StripePermissionError

ProblemaLa chiave API utilizzata per questa richiesta non dispone delle autorizzazioni necessarie.
Soluzioni
  • Assicurati di non utilizzare una chiave API con limitazioni per un servizio a cui questa non può accedere.
  • Non eseguire azioni nella Dashboard se hai effettuato l’accesso con un ruolo utente non autorizzato.

Errori di limitazione della velocità

Tipo

StripeRateLimitError

ProblemaHai effettuato troppe chiamate API in troppo poco tempo.
Soluzioni
  • Se una sola chiamata API attiva questo errore, attendi e riprova.
  • Per gestire la limitazione di frequenza in automatico, ritenta la chiamata API dopo un ritardo e, se l’errore persiste, aumenta il ritardo in modo esponenziale. Per ulteriori informazioni, consulta la documentazione sui limiti di frequenza.
  • Se prevedi un forte aumento del traffico e desideri richiedere un limite di frequenza maggiore, contatta l’assistenza in anticipo.

Errori di verifica di firma

Tipo

StripeSignatureVerificationError

ProblemaStai usando la verifica della firma del webhook e non abbiamo potuto verificare l’autenticità di un evento webhook.

Soluzioni

Questo errore può verificarsi quando la tua integrazione funziona correttamente. Se usi la verifica di firma del webhook e una terza parte tenta di inviarti un webhook falso o dannoso, la verifica ha esito negativo e questo errore è il risultato. Rilevalo e rispondi con un codice stato 400 Bad Request.

Se ricevi questo errore quando non dovresti (ad esempio, con webhook che sai che provengono da Stripe) consulta la documentazione relativa alla verifica delle firme dei webhook in cui troverai ulteriori informazioni. In particolare, assicurati di usare la chiave privata dell’endpoint corretta. Questa chiave è diversa dalla tua chiave API.

Questa pagina è stata utile?
SìNo
Hai bisogno di aiuto? Contatta l'assistenza clienti.
Partecipa al nostro programma di accesso anticipato.
Dai un'occhiata al nostro registro delle modifiche.
Domande? Contattaci.
LLM? Leggi llms.txt.
Realizzato da Markdoc