Gestion avancée des erreurs

Cette page aborde deux sujets de gestion avancée des erreurs :

• Réponses HTTP qui représentent des erreurs
• Idempotence et relances

Cette information ne s’applique peut-être pas à votre cas. Les SDK officielles de Stripe peuvent gérer la plupart des informations concernant le protocole HTTP et les relances. Si vous utilisez une bibliothèque client, commencez par consulter les sections suivantes :

• Gestion des erreurs
• Codes d’erreur

Erreurs liées au protocole HTTP

Même en cas d’échec d’un appel à l’API, nos bibliothèques clients rendent les données sur les erreurs disponibles en générant une exception ou en retournant une valeur d’erreur. Cependant, si vous n’utilisez pas de bibliothèque client, ou si une situation inhabituelle surgit, vous pourriez avoir besoin d’informations de bas niveau à propos des réponses HTTP et des moments où nous les émettons.

Dans le cadre du protocole HTTP, les erreurs se répartissent en trois grandes catégories :

• Erreur de contenu : le contenu de la requête envoyée à l’API n’est pas valide.
• Erreur réseau : des problèmes de communication surviennent par intermittence entre le client et le serveur.
• Erreur de serveur : un problème est survenu sur les serveurs de Stripe.

Chaque type d’erreur nécessite une approche différente et des principes d’idempotence. Une liste complète des codes de réponse et de leur signification est fournie à la fin de cette page.

Erreurs de contenu

Les erreurs de contenu sont dues à un contenu de requête API non valide. Elles renvoient une réponse HTTP associée à un code de réponse 4xx. Par exemple, les serveurs de l’API peuvent renvoyer une erreur 401 si une clé API non valide a été fournie ou une erreur 400 si un paramètre obligatoire est manquant. Les intégrations doivent corriger la requête à l’origine de l’erreur, puis la relancer. En fonction du type d’erreur utilisateur (par exemple, une carte refusée), il peut être possible de résoudre le problème de manière programmatique. Dans ce cas, incluez un champ code pour permettre à l’intégration de réagir de manière appropriée. Consultez la section consacrée aux codes d’erreur pour en savoir plus.

Dans le cas d’une opération POST qui utilise une clé d’idempotence, les serveurs de l’API Stripe mettront en cache les résultats, quels qu’ils soient, dans la mesure où une méthode de l’API a commencé à s’exécuter. Une requête renvoyant un code d’erreur 400 renverra ce même code d’erreur 400 si elle est renouvelée en utilisant la même clé d’idempotence. Vous devez générer une nouvelle clé d’idempotence pour aboutir au résultat voulu si vous avez modifié la requête d’origine. Toutefois, cette méthode n’est pas parfaite. Par exemple, une requête subissant une limite de tentatives et renvoyant une erreur 429 peut générer un résultat différent avec la même clé, car les limiteurs s’exécutent avant la couche d’idempotence de l’API. Il en va de même pour un code 401 lié à l’absence de clé API et pour la plupart des codes 400 liés à des paramètres non valides. Malgré tout, en cas d’erreur 4xx, il est préférable de toujours générer une nouvelle clé d’idempotence.

Erreurs réseau

Les erreurs réseau sont le résultat de problèmes de connectivité entre le client et le serveur. Elles renvoient des erreurs de bas niveau, comme des erreurs de socket ou des erreur d’expiration du délai d’attente. Par exemple, un client peut recevoir un avis d’expiration pendant une tentative de lecture sur les serveurs Stripe ou ne jamais recevoir de réponse de l’API, car la connexion a pris fin de manière prématurée. Même s’il semble que l’erreur réseau soit résolue après la correction des problèmes de connectivité, il peut arriver que ce problème intermittent cache un autre type d’erreur.

Ce type d’erreur met en évidence l’intérêt des clés d’idempotence et des renouvellements des requêtes. Lorsque des problèmes intermittents surviennent, les clients ne savent généralement pas si le serveur a reçu ou non leur requête. Pour s’en assurer, ils doivent renouveler ces requêtes en conservant les mêmes clés d’idempotence et paramètres jusqu’à l’obtention d’une réponse. L’envoi d’une clé d’idempotence identique avec des paramètres différents génère une erreur indiquant que la nouvelle requête ne correspond pas à celle d’origine.

La plupart des bibliothèques clients peuvent générer des clés d’idempotence et renouveler des requêtes automatiquement, mais elles doivent être configurées à cet effet. Elles effectuent la première relance tout de suite après le premier échec, puis les tentatives suivantes interviennent à des intervalles de plus en plus longs. L’idée derrière cette stratégie est qu’un échec de paiement unique peut être tout à fait ponctuel, mais que des défaillances répétées sont vraisemblablement le signe d’un problème chronique.

Stripe.max_network_retries = 2

Erreurs de serveur

Les erreurs de serveur résultent d’un problème au niveau des serveurs de Stripe et renvoient une réponse HTTP associée à un code d’erreur 5xx. Ces erreurs sont les plus difficiles à gérer, et nous faisons notre possible pour les éviter au maximum. Toutefois, une intégration efficace doit être en mesure de les traiter dans les rares cas où elles surviennent.

Comme pour les erreurs utilisateur, la couche d’idempotence met en cache les résultats des mutations POST aboutissant à des erreurs de serveur (en particulier pour les codes 500, synonymes d’erreurs de serveur internes), de sorte que leur relance avec la même clé d’idempotence aboutit généralement au même résultat. Le client peut relancer la requête avec une nouvelle clé, mais nous déconseillons cette approche, car la clé d’origine a pu générer des effets secondaires.

Nous vous conseillons de traiter le résultat d’une requête générant un code 500 comme indéterminé. Ce type d’erreur se produit le plus souvent lors de la survenue d’un incident en production et de la phase de résolution d’un tel incident. Les ingénieurs de Stripe examinent les requêtes ayant échoué et essaient de rapprocher les résultats de toute mutation ayant généré une erreur 500. Même si la réponse à ces requêtes enregistrée dans le cache d’idempotence ne change pas, nous essaierons de déclencher des webhooks pour tout nouvel objet créé lors du rapprochement effectué par Stripe. La nature exacte des changements appliqués de manière rétroactive au système dépend fortement du type de la requête. Par exemple, si la création d’un débit génère une erreur 500, mais que nous détectons que l’information a été transmise à un réseau de paiement, nous l’appliquerons. Sinon, nous essaierons de l’annuler. Si ce changement ne résout pas le problème, vous pourrez toujours être confronté à des requêtes générant une erreur 500 et des effets visibles par l’utilisateur de nature variée.

Pour déléguer la gestion des codes 500 à votre intégration, configurez des gestionnaires de webhooks afin de recevoir des objets d’événements que vous ne recevez pas habituellement lors de requêtes à l’API. Pour associer ces nouveaux objets aux données de l’état local d’une intégration, vous pouvez envoyer un identifiant local avec les métadonnées lors de la création de nouvelles ressources avec l’API. Cet identifiant apparaît dans le champ des métadonnées d’un objet envoyé via un webhook, même si le webhook est généré ultérieurement, lors du rapprochement.

Idempotence

L’idempotence est un principe de fonctionnement d’une API Web consistant à permettre d’effectuer une même opération plusieurs fois sans pour autant modifier le résultat au-delà de la première tentative. Il est donc sans risque de relancer des requêtes API dans certaines situations, en particulier lorsque la première requête n’obtient pas de réponse suite à une erreur réseau. Dans la mesure où des dysfonctionnements occasionnels sont inévitables, les clients doivent pouvoir rapprocher les requêtes en échec d’un serveur, ce que facilite l’idempotence.

La plupart des bibliothèques clients peuvent générer des clés d’idempotence et renouveler des requêtes automatiquement, mais vous devez configurer cette action. Pour un contrôle plus précis des relances, veuillez générer des clés d’idempotence et écrire votre propre logique de relance.

Requêtes GET et DELETE

L’API de Stripe garantit l’idempotence des requêtes GET et DELETE, il n’y a donc jamais de risque à les relancer.

Requêtes POST

En incluant une clé d’idempotence, vous rendez vos requêtes POST idempotentes, c’est-à-dire que vous demandez à l’API de tenir des registres afin d’éviter les doublons. Les clients peuvent relancer les requêtes incluant une clé d’idempotence en toute sécurité, à condition que la deuxième requête soit effectuée dans les 24 heures suivant l’obtention de la clé (les clés sont effacées du système au bout de 24 heures.) Par exemple, si une requête de création d’un objet n’aboutit pas en raison d’une erreur de connexion réseau, le client peut relancer la requête en utilisant la même clé d’idempotence, ce qui évite de créer plusieurs objets par accident.

Envoi de clés d’idempotence

Les clés d’idempotence sont envoyées dans l’en-tête Idempotency-Key. Utilisez-les pour toutes les requêtes POST à l’API Stripe. La plupart des bibliothèques clients officielles peuvent les envoyer automatiquement, dès lors qu’elles sont configurées pour l’envoi de relances.

Si vous choisissez d’envoyer des clés d’idempotence manuellement, vérifiez que les tokens utilisés soient suffisamment distinctifs pour identifier toutes les opérations effectuées sur votre compte au cours des dernières 24 heures au moins, sans ambiguïté possible. Deux stratégies sont fréquemment utilisées pour générer des clés d’idempotence :

• Utiliser un algorithme pouvant générer un token de manière suffisamment aléatoire, par exemple UUID v4.
• Dériver la clé d’un objet associé à un utilisateur, par exemple l’ID d’un panier d’achat. Cette méthode permet de prévenir les doublons de manière relativement simple.

Pour repérer une réponse déjà exécutée et retransmise par le serveur, recherchez l’en-tête Idempotent-Replayed: true.

L’en-tête Stripe-Should-Retry

Une bibliothèque client ne peut pas toujours déterminer avec certitude si elle doit renouveler une requête sur la seule base d’un code d’état ou du contenu du corps de la réponse. L’API répond avec l’en-tête Stripe-Should-Retry lorsqu’elle dispose d’informations supplémentaires lui permettant de recommander le renouvellement de la requête.

• Lorsque l’en-tête Stripe-Should-Retry est défini sur true, le client doit relancer la requête. Toutefois, il doit attendre un certain temps (généralement un délai exponentiel) afin de ne pas surcharger l’API.
• Lorsque l’en-tête Stripe-Should-Retry est défini sur false, le client ne doit pas relancer la requête, car la nouvelle tentative ne changera rien.
• Lorsque l’en-tête Stripe-Should-Retry n’est pas défini dans la réponse, cela signifie que l’API ne peut pas déterminer si la requête doit être relancée ou non. Les clients doivent donc s’appuyer sur d’autres propriétés de la réponse (comme le code d’état) pour prendre leur décision.

Les mécanismes de relance des requêtes intégrés aux bibliothèques clients Stripe respectent automatiquement l’en-tête Stripe-Should-Retry. Si vous utilisez l’une d’elles, vous n’avez aucune gestion manuelle à faire.

Référence des codes d’état HTTP