Accéder directement au contenu
Créez un compte
ou
connecter-vous
Logo de la documentation Stripe
/
Demander à l'assistant IA
Créez un compte
Connectez-vous
Démarrer
Paiements
Revenus
Plateformes et places de marché
Gestion de fonds
Ressources pour les développeurs
Aperçu
Gestion des versions
Journal des modifications
Mettre à niveau votre version de l'API
Actualiser votre version du SDK
Essentials
SDK
API
    API v2
    Clés API
    En-tête Stripe-Context
    Limites de débit
    Tests automatiques
    Métadonnées
    Développement des réponses
    Pagination
    Domaines et adresses IP
    Rechercher
    Localisation
    Gestion des erreurs
      Gestion avancée des erreurs
    Codes d'erreur
Tests
CLI Stripe
Exemples de projets
Outils
Workbench
Dashboard des développeurs
Shell Stripe
Stripe pour Visual Studio Code
Fonctionnalités
Workflows
Destinations d'événements
Alertes d'intégrité de StripeChargements de fichiers
Solutions d'IA
Boîte à outils des agents
Modèle de protocole contextuel
Sécurité et confidentialité
Sécurité
Confidentialité
Extensions Stripe
Créer des applications Stripe
Utiliser les applications de Stripe
Partenaires
Partner ecosystem
Certification des partenaires
AccueilRessources pour les développeursAPI

Gestion des erreurs

Capturez et répondez aux refus de paiement, aux données non valides, aux problèmes de réseau et plus.

Stripe présente plusieurs types d’erreurs, qui peuvent désigner des événements extérieurs, tels que des refus de paiement et des interruptions réseau, ou bien des problèmes de code, comme des appels à l’API non valides.

Analyser les données d’erreur

Lorsque Stripe renvoie une erreur à votre requête d’API, vous recevez des informations sur l’erreur qui vous aident à comprendre comment appliquer les suggestions de traitement de ce guide. Ces détails vous permettent également de fournir des informations importantes à l’équipe Support de Stripe, le cas échéant.

PropriétéDescription
codeLe code d’erreur.
doc_urlLien vers la documentation Stripe concernant le code d’erreur en question.
messageDescription de la raison de l’erreur.
paramParamètre de la requête responsable de l’erreur.
request_log_urlLien vers le Dashboard Stripe où vous pouvez consulter les logs détaillés de la requête initiale et de l’erreur.
ID de la demandeIdentifiant unique pour la requête d’origine ayant généré l’erreur. L’en-tête de réponse à l’erreur inclut cette valeur (chaîne commençant par req), mais vous pouvez spécifier une impression dans votre requête, comme indiqué dans les exemples de code de ce guide.
typeRéférence à la catégorie d’erreur à laquelle cette erreur appartient.

Utilisez certaines ou toutes les techniques présentées dans le tableau ci-dessous afin de traiter les erreurs. Peu importe la technique utilisée, vous pouvez poursuivre avec nos réponses recommandées pour chaque type d’erreur.

TechniqueObjectifNécessaire
Utiliser les valeurs d’erreurRectifier les problèmes en cas d’interruption d’un appel à l’APISystématiquement
Surveiller les webhooksRéagir aux notifications de StripeParfois
Obtenir des informations enregistrées sur les échecsAnalyser les problèmes passés et prendre en charge d’autres techniquesParfois

Utiliser des valeurs d’erreur

Erreurs et HTTP

Avec cette bibliothèque, vous n’avez pas besoin de vérifier les réponses autres que les réponses HTTP 200. La bibliothèque les traduit en valeurs d’erreur.

Dans les rares cas où vous auriez besoin d’informations HTTP, consultez les pages consacrées à la gestion des exceptions de bas niveau et à l’objet Error.

Les appels à l’API dans la bibliothèque Go de Stripe retournent une valeur de résultat et une valeur d’erreur. Utilisez des attributions multiples pour capturer ces deux valeurs. Si la valeur d’erreur n’est pas nil, cela signifie qu’un problème immédiat a empêché la poursuite de l’appel à l’API.

Si la valeur de l’erreur concerne Stripe, vous pouvez la convertir en objet stripe.Error qui contient des champs décrivant le problème. Utilisez le champ Type pour choisir une réponse. Dans certains cas, vous pouvez convertir la propriété Err en un type d’erreur plus spécifique avec des informations complémentaires.

Ruby
Python
PHP
Java
Node
Go
.NET
No results
package main import ( "github.com/stripe/stripe-go/v72" "github.com/stripe/stripe-go/v72/paymentintent" "log" ) func example_function(params *stripe.PaymentIntentParams) { stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
_, err := paymentintent.New(params) if err == nil { log.Println("No error.") } else { if stripeErr, ok := err.(*stripe.Error); ok { log.Fatalf("request id: %s", stripeErr.RequestID) switch stripeErr.Type { case stripe.ErrorTypeCard: log.Println("A payment error occurred:", stripeErr.Msg) case stripe.ErrorTypeInvalidRequest: log.Println("An invalid request occurred.") default: log.Println("Another Stripe error occurred.") } } else { log.Println("An error occurred that was unrelated to Stripe.") } } }

Une fois que vous avez configuré la manière de gérer les exceptions, effectuez des tests sur divers types de données, y compris des cartes de test, afin de simuler différents résultats de paiement.

Ruby
Python
PHP
Java
Node
Go
.NET
No results
params := &stripe.PaymentIntentParams{ Amount: stripe.Int64(2000), // The required parameter currency is missing Confirm: stripe.Bool(true), PaymentMethod: stripe.String(
"pm_card_visa"
), } example_function(params)
console
Ruby
Python
PHP
Java
Node
Go
.NET
No results
1754136607 An invalid request occurred.

Surveiller les webhooks

En cas de problème, Stripe vous avertit à l’aide de webhooks, y compris pour les problèmes qui ne surviennent pas immédiatement après un appel à l’API. Par exemple :

  • Vous perdez un litige.
  • Un paiement récurrent échoue après plusieurs mois sans souci.
  • Votre front-end confirme un paiement, mais passe hors ligne avant l’échec du paiement. (Le back-end reçoit quand même une notification de webhook, même s’il n’a pas effectué l’appel à l’API.)

Il n’est pas nécessaire de traiter tous les types d’événements webhook. En réalité, certaines intégrations n’en traitent aucun.

Dans votre gestionnaire de webhooks, commencez par suivre les étapes de base de l’outil de création de webhook : prenez un objet Event et servez-vous du type d’événement pour découvrir ce qui s’est passé. Ensuite, si le type d’événement indique une erreur, suivez ces étapes supplémentaires :

  1. Récupérez l’objet concerné en désérialisant les données de event.Data.Raw.
  2. Utilisez les informations stockées dans l’objet concerné pour obtenir des explications, y compris dans le cas d’un objet Error.
  3. Référez-vous au type de l’objet pour déterminer la marche à suivre.
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
package main import ( "encoding/json" "io/ioutil" "log" "net/http" "github.com/stripe/stripe-go/v72" "github.com/stripe/stripe-go/v72/webhook" ) func main() { http.HandleFunc("/webhook", handleWebhook) addr := "localhost:4242" log.Printf("Listening on %s", addr) log.Fatal(http.ListenAndServe(addr, nil)) } func handleWebhook(w http.ResponseWriter, req *http.Request) { const MaxBodyBytes = int64(65536) req.Body = http.MaxBytesReader(w, req.Body, MaxBodyBytes) payload, err := ioutil.ReadAll(req.Body) if err != nil { log.Printf("Error reading request body: %v\n", err) w.WriteHeader(http.StatusServiceUnavailable) return } // Replace this endpoint secret with your endpoint's unique secret // If you are testing with the CLI, find the secret by running 'stripe listen' // If you are using an endpoint defined with the API or dashboard, look in your webhook settings // at https://dashboard.stripe.com/webhooks endpointSecret := "whsec_..." signatureHeader := req.Header.Get("Stripe-Signature") // Get an event object event, err := webhook.ConstructEvent(payload, signatureHeader, endpointSecret) if err != nil { log.Printf("⚠️ Webhook signature verification failed. %v\n", err) w.WriteHeader(http.StatusBadRequest) // Return a 400 error on a bad signature return } // Use its type to find out what happened switch event.Type { case "payment_intent.payment_failed": // Get the object affected by unmarshalling event data into // the appropriate struct for the event type var paymentIntent stripe.PaymentIntent err := json.Unmarshal(event.Data.Raw, &paymentIntent) if err != nil { log.Printf("Error parsing webhook JSON: %v\n", err) w.WriteHeader(http.StatusBadRequest) return } // Use stored data to get an error object e := paymentIntent.LastPaymentError // Use its type to choose a response switch e.Type { case "card_error": log.Println("A payment error occurred: ", e.Msg) case "invalid_request": log.Println("An invalid request occurred.") default: log.Println("Another problem occurred, maybe unrelated to Stripe.") } default: log.Println("Unhandled event type: ", event.Type) } w.WriteHeader(http.StatusOK) }

Pour tester la réponse de votre intégration aux événements webhook, vous pouvez déclencher des événements webhook localement. Après avoir terminé les étapes de configuration sur ce lien, déclenchez un échec de paiement pour voir le message d’erreur qui en résulte.

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

Obtenir des informations enregistrées sur les échecs

De nombreux objets stockent des informations sur les échecs. Cela signifie que s’il y a déjà eu un problème, vous êtes en mesure de récupérer l’objet et de l’examiner afin d’en savoir plus. Les informations stockées se présentent généralement sous la forme d’un objet Error, et vous pouvez vous référer à sa classe pour déterminer la marche à suivre.

Par exemple :

  1. Récupérez un PaymentIntent spécifique.
  2. Vérifiez s’il y a eu une erreur de paiement en déterminant si l’objet last_payment_error est vide.
  3. Si c’est le cas, consignez l’erreur en incluant son type et l’objet concerné.
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
pi, _ := paymentintent.Get(
"{{PAYMENT_INTENT_ID}}"
, nil, ) paymentErr := pi.LastPaymentError if paymentErr != nil { log.Printf("PaymentIntent %s experienced a %s error.", pi.ID, paymentErr.Type) }

Voici quelques objets courants qui stockent des informations sur les échecs.

ObjetAttributValeurs
Payment Intentslast_payment_errorUn objet Error
Setup Intentslast_setup_errorUn objet Error
Invoicelast_finalization_errorUn objet Error
Setup Attemptsetup_errorUn objet Error
Virementfailure_codeUn code d’échec de virement
Refundfailure_reasonUn code d’échec de remboursement

Pour tester un code qui exploite des informations enregistrées à propos des échecs, vous serez parfois amené à simuler des échecs de transactions. Pour cela, utilisez des cartes de test ou des numéros de comptes bancaires de test. Par exemple :

  • Simuler un refus de paiement pour générer des échecs de Charges, PaymentIntents, SetupIntents et autres.
  • Simuler un échec de virement.
  • Simuler un échec de remboursement.

Types d’erreurs et réponses

Dans la bibliothèque Go de Stripe, chaque objet Error possède un attribut Type. Référez-vous à la documentation concernant chaque classe pour obtenir des conseils quant aux réponses à apporter.

Nom

Type

Description
Erreur de paiement

stripe.ErrorTypeCard

Une erreur est survenue lors d’un paiement. Voici les cas possibles :
  • Paiement bloqué pour suspicion de fraude
  • Paiement refusé par l’émetteur.
  • Autres erreurs de paiement.
Erreur de requête non valide

stripe.ErrorTypeInvalidRequest

L’appel à l’API que vous avez effectué n’est pas valide. Cela peut être dû à l’une des raisons suivantes :

  • Erreur de limitation d’envoi
  • Erreur d’authentification
  • Paramètres ou état non valides
Erreur d’API

stripe.ErrorTypeAPI

Un problème est survenu au niveau de Stripe (cas rare).
Erreur d’idempotence

stripe.ErrorTypeIdempotency

Vous avez utilisé une clé d’idempotence pour effectuer une action inattendue (par exemple, relancer une requête en transmettant des paramètres différents).

Erreurs de carte

Erreurs de paiement hors cartes bancaires

Toutes les dispositions de cette section s’appliquent également aux paiements autres que par carte. Pour des raisons historiques, les erreurs de paiement sont de type stripe.ErrorTypeCard. Dans les faits, toutefois, ils peuvent représenter un problème avec n’importe quel paiement, quel que soit le moyen de paiement.

Les erreurs de paiement, parfois appelées « erreurs de carte » pour des raisons historiques, regroupe un grand nombre de problèmes courants. Elles sont réparties en trois catégories :

  • Paiement bloqué pour suspicion de fraude
  • Paiement refusé par l’émetteur
  • Autres erreurs de paiement

Pour pouvoir distinguer ces catégories ou en savoir davantage sur la façon d’y répondre, reportez-vous aux pages relatives aux codes d’erreur, aux codes de refus de paiement et aux résultats du paiement.

(Pour rechercher un résultat de paiement à partir d’un objet Error, récupérez d’abord le PaymentIntent correspondant ainsi que le dernier paiement que ce dernier a créé. L’exemple ci-après illustre cette étape.)

Ruby
Python
PHP
Java
Node
Go
.NET
No results
func example_function(params *stripe.PaymentIntentParams) { stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
_, err := paymentintent.New(params) if err == nil { log.Println("No error.") } else { if stripeErr, ok := err.(*stripe.Error); ok { if stripeErr.Type == stripe.ErrorTypeCard { charge = Charge.retrieve(stripeErr.PaymentIntent.LatestCharge) if charge.Outcome.Type == "blocked" { log.Println("Payment blocked for suspected fraud.") } else if stripeErr.Code == stripe.ErrorCodeCardDeclined { log.Println("Declined by the issuer.") } else if stripeErr.Code == stripe.ErrorCodeExpiredCard { log.Println("Card expired.") } else { log.Println("Other card error.") } } } } }

Utilisateurs de la version du 01/08/2022 de l’API ou d’une version antérieure :

(Pour rechercher un résultat de paiement à partir d’un objet Error, récupérez d’abord le PaymentIntent correspondant ainsi que le dernier paiement que ce dernier a créé. L’exemple ci-après illustre cette étape.)

Ruby
Python
PHP
Java
Node
Go
.NET
No results
func example_function(params *stripe.PaymentIntentParams) { stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
_, err := paymentintent.New(params) if err == nil { log.Println("No error.") } else { if stripeErr, ok := err.(*stripe.Error); ok { if stripeErr.Type == stripe.ErrorTypeCard { if stripeErr.PaymentIntent.Charges.Data[0].Outcome.Type == "blocked" { log.Println("Payment blocked for suspected fraud.") } else if stripeErr.Code == stripe.ErrorCodeCardDeclined { log.Println("Declined by the issuer.") } else if stripeErr.Code == stripe.ErrorCodeExpiredCard { log.Println("Card expired.") } else { log.Println("Other card error.") } } } } }

Grâce aux cartes de test, vous pouvez déclencher certains types d’erreur de paiement courants. Consultez ces listes pour connaitre les démarches à suivre :

  • Simulation de paiements bloqués en raison d’un risque de fraude
  • Simulation de refus de paiements et d’autres erreurs de carte

Le code de test ci-dessous montre quelques possibilités.

Ruby
Python
PHP
Java
Node
Go
.NET
No results
params := &stripe.PaymentIntentParams{ Amount: stripe.Int64(2000), Currency: stripe.String(string(stripe.CurrencyUSD)), Confirm: stripe.Bool(true), PaymentMethod: stripe.String(
"pm_card_radarBlock"
), } example_function(params)
console
Ruby
Python
PHP
Java
Node
Go
.NET
No results
1754136607 Payment blocked for suspected fraud.

Bloqué pour suspicion de fraude

Type

stripe.ErrorTypeCard

Codes
charge = Charge.retrieve(stripeErr.PaymentIntent.LatestCharge) charge.Outcome.Type == "blocked"
Codes

stripeErr.PaymentIntent.Charges.Data[0].Outcome.Type == "blocked"

ProblèmeRadar, le système de prévention des fraudes de Stripe, a bloqué le paiement

Solutions

Cette erreur peut se produire alors que votre intégration fonctionne correctement. Capturez-la et invitez le client à utiliser un autre moyen de paiement.

Pour bloquer moins de paiements légitimes, suivez la procédure ci-après :

  • Optimisez votre intégration Radar pour collecter des informations plus détaillées.
  • Pour obtenir des éléments de formulaire optimisés préconfigurés, utilisez Payment Links, Checkout ou Stripe Elements.

Les clients de Radar for Fraud Teams disposent des options supplémentaires suivantes :

  • Pour exempter un paiement spécifique, ajoutez-le à votre liste blanche. Radar for Fraud Teams
  • Pour modifier votre seuil de tolérance au risque, réajustez les paramètres de risque. Radar for Fraud Teams
  • Pour modifier les critères de blocage des paiements, définissez des règles personnalisées. Radar for Fraud Teams

Vous pouvez tester les paramètres de votre intégration à l’aide de cartes de test qui permettent de simuler des fraudes. Si vous avez défini des règles Radar personnalisées, suivez les conseils en matière de test décrits dans la documentation de Radar.

Refusé par l’émetteur

Type

stripe.ErrorTypeCard

Codes

cardErr.Error.Code == stripe.ErrorCodeCardDeclined

ProblèmeL’émetteur de la carte a refusé le paiement.

Solutions

Cette erreur peut se produire alors que votre intégration fonctionne correctement. Elle reflète une action effectuée par l’émetteur, qui peut être légitime. Utilisez le code de refus de paiement pour déterminer la marche à suivre. Consultez la documentation sur les codes de refus de paiement pour connaître les réponses adaptées à chaque code.

Vous pouvez également effectuer les actions ci-après :

  • Suivez nos recommandations pour limiter les refus de paiement des émetteurs.
  • Pour obtenir des éléments de formulaire préconfigurés qui puissent mettre en œuvre ces recommandations, utilisez Payment Links, Checkout ou Stripe Elements.

Analysez la façon dont votre intégration gère les refus de paiement à l’aide de cartes de test qui permettent de simuler des paiements aboutis et refusés.

Autres erreurs de paiement

Type

stripe.ErrorTypeCard

ProblèmeUne autre erreur de paiement s’est produite.
SolutionsCette erreur peut se produire alors que votre intégration fonctionne correctement. Utilisez le code d’erreur pour déterminer la marche à suivre. Consultez la documentation consacrée à ce sujet pour découvrir les réponses adaptées à chaque code.

Erreurs de requêtes invalides

Les erreurs de requêtes invalides couvrent de nombreuses situations. La plus courante survient quand la requête à l’API contient des paramètres non valides ou si l’état actuel de votre intégration ne permet pas son exécution. Utilisez le code d’erreur (stripeErr.Code) et consultez la documentation consacrée aux codes d’erreur afin de trouver une solution. Certains codes d’erreur nécessitent une réponse spéciale :

  • rate_limit et lock_timeout reflètent les erreurs de limite l’envoi
  • secret_key_required désigne une erreur d’authentification
  • D’autres codes d’erreur reflètent un des paramètres ou un état non valides

Erreurs de limite d’envoi

Type

stripe.ErrorTypeInvalidRequest

CodesstripeErr.Code == stripe.ErrorCodeRateLimit or stripeErr.Code == stripe.ErrorCodeLockTimeout
ProblèmeVous avez effectué trop d’appels à l’API dans le délai imparti.
Solutions
  • Si un seul appel à l’API déclenche cette erreur, réessayez ultérieurement.
  • Pour gérer la limitation d’envoi de façon automatique, retentez l’appel à l’API après quelques minutes et augmentez exponentiellement le délai si l’erreur persiste. Pour obtenir plus de conseils, consultez la documentation sur les limites d’envoi.
  • Si vous prévoyez une augmentation importante du trafic et que vous souhaitez demander une limite d’envoi plus souple, contactez notre service Support en amont.

Erreurs d’authentification

Type

stripe.ErrorTypeInvalidRequest

CodesstripeErr.Code == stripe.ErrorCodeSecretKeyRequired
ProblèmeStripe ne parvient pas à vous authentifier avec les informations que vous avez fournies.
Solutions
  • Utilisez la clé API appropriée.
  • Veillez à ne pas utiliser une clé que vous avez « générée aléatoirement » ou révoquée.

Paramètres ou état non valides

Type

stripe.ErrorTypeInvalidRequest

CodesstripeErr.Code != stripe.ErrorCodeRateLimit and stripeErr.Code != stripe.ErrorCodeLockTimeout and stripeErr.Code != stripe.ErrorCodeSecretKeyRequired
ProblèmeVous avez effectué un appel à l’API contenant des paramètres incorrects, dont l’état est incompatible ou d’une manière non valide.
SolutionsDans la plupart des cas, le problème vient de la requête elle-même : soit ses paramètres ne sont pas valides, soit l’état actuel de votre intégration ne permet pas son exécution.
  • Pour en savoir plus à propos de ce problème, consultez la documentation consacrée aux codes d’erreur.
  • Pour des raisons pratiques, vous pouvez suivre le lien stripeErr.DocURL pour en savoir plus sur le code d’erreur.
  • Si l’erreur implique un paramètre précis, utilisez stripeErr.Param pour savoir duquel il s’agit.

Erreurs d’API

Type

stripe.ErrorTypeAPI

ProblèmeUn problème est survenu au niveau de Stripe (cas rare).

Solutions

Traitez le résultat de l’appel à l’API comme étant indéterminé. Autrement dit, ne partez pas du principe qu’il a abouti ou échoué.

Appuyez-vous sur les webhooks pour obtenir des informations sur le résultat. Lorsque cela est possible, Stripe déclenche des webhooks pour tous les nouveaux objets créés pendant la résolution du problème.

Pour configurer votre intégration de sorte à ce qu’elle soit capable de gérer des situations inhabituelles, reportez-vous à cette section plus avancée consacrée aux erreurs de serveur.

Erreurs d’idempotence

Type

stripe.ErrorTypeIdempotency

ProblèmeVous avez utilisé une clé d’idempotence pour effectuer une action inattendue (par exemple, relancer une requête en transmettant des paramètres différents).
Solutions
  • Une fois que vous avez utilisé une clé d’idempotence, ne la réutilisez que pour effectuer des appels à l’API identiques.
  • Utilisez des clés d’idempotence dont la longueur ne dépasse pas 255 caractères.
Cette page vous a-t-elle été utile ?
OuiNon
  • Besoin d'aide ? Contactez le service Support.
  • Rejoignez notre programme d'accès anticipé.
  • Consultez notre log des modifications.
  • Des questions ? Contactez l'équipe commerciale.
  • LLM ? Lire llms.txt.
  • Propulsé par Markdoc