Traitement avancé des erreurs

Cette page aborde deux sujets du traitement avancé des erreurs :

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

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

• Traitement des erreurs
• Codes d’erreur

Erreurs dans HTTP

Même en cas d’échec d’un appel à l’API, nos bibliothèques client fournissent des informations sur les erreurs en générant une exception ou en renvoyant une valeur d’erreur. Mais si vous n’utilisez pas de bibliothèque client, ou si une situation inhabituelle se présente, vous aurez peut-être besoin d’informations de bas niveau sur les réponses HTTP et sur le moment auquel elles sont émises.

D’un point de vue HTTP, les erreurs relèvent de trois grandes catégories :

• Erreur de contenu : La requête envoyée à l’API présente un contenu non valide.
• Erreur de 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. La liste complète des codes de réponse et leur signification sont indiqués à la fin de cette page.

Erreurs de contenu

Les erreurs de contenu proviennent d’un contenu non valide d’une requête API. Elles renvoient une réponse HTTP avec un code de réponse 4xx. Par exemple, les serveurs API peuvent renvoyer une erreur 401 si vous avez fourni une clé API non valide, ou une erreur 400 s’il manque un paramètre obligatoire. Les intégrations doivent corriger la demande initiale et réessayer. Selon le type d’erreur de l’utilisateur (par exemple, une carte refusée), il peut être possible de gérer le problème par voie programmatique. Dans ce cas, incluez un champ code pour aider une intégration à réagir de manière appropriée. Pour en savoir plus, veuillez consulter la page Codes d’erreur.

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 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 de réseau découlent de problèmes de connectivité entre le client et le serveur. Elles renvoient des erreurs de bas niveau, comme des erreurs de connecteur logiciel ou des exceptions de délai d’inactivité. Par exemple, un client peut recevoir un message délai d’inactivité pendant qu’il tente de lire les données sur les serveurs Stripe, ou ne jamais recevoir une réponse de l’API, car la connexion s’est terminée prématurément. Bien qu’une erreur réseau semble être réglée une fois que vous avez résolu les problèmes de connectivité, il arrive parfois qu’un autre type d’erreur soit dissimulé dans le problème intermittent.

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 du serveur. 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 client peuvent générer des clés d’idempotence et relancer des requêtes automatiquement, mais doivent être configurées à cet effet. Elles relancent la requête très rapidement après le premier échec, puis les tentatives suivantes sont effectuées à des intervalles exponentiellement plus longs. L’idée derrière cette stratégie est qu’une défaillance unique peut être ponctuelle, mais que des défaillances répétées sont le signe d’un problème chronique.

Stripe.max_network_retries = 2

Erreurs de serveur

Les erreurs de serveur proviennent d’un problème au niveau des serveurs de Stripe. Elles renvoient une réponse HTTP avec un code de réponse 5xx. Ces erreurs sont les plus difficiles à gérer et nous faisons notre possible pour les éviter au maximum, mais une intégration efficace les traite lorsqu’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 renouvellement avec la même clé d’idempotence aboutit généralement au même résultat. Le client peut renouveler la requête avec une nouvelle clé d’idempotence, mais nous déconseillons cette stratégie, car la clé d’origine a pu générer des effets secondaires.

Vous devez considérer le résultat d’une requête 500 comme indéterminé. Le moment le plus probable pour en observer un est lors d’un incident de production, et généralement lors de la correction d’un tel incident. Les ingénieurs de Stripe examinent les requêtes qui ont échoué et tentent de rapprocher de manière appropriée les résultats de toutes les mutations qui aboutissent à 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 liens de rappel HTTP 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 cela ne résout pas le problème, des requêtes générant une erreur 500 peuvent toujours se produire, avec des effets secondaires visibles par l’utilisateur.

Pour permettre à votre intégration de gérer le plus grand nombre de 500, configurez les gestionnaires de liens de rappel pour recevoir des objets d’événement que vous ne recevez jamais dans les réponses normales de 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 est affiché dans le champ des métadonnées d’un objet envoyé au moyen d’un lien de rappel, même si le lien de rappel est généré ultérieurement, lors du rapprochement.

Idempotence

L’idempotence est un principe de conception des API Web défini comme la possibilité d’appliquer la même opération plusieurs fois sans modifier le résultat au-delà du premier essai. Il est donc sans risque de relancer les requêtes API dans certaines situations, notamment lorsque la première requête ne reçoit pas de réponse en raison d’une erreur de réseau. Dans la mesure où des défaillances intermittentes sont inévitables, les clients doivent disposer d’un moyen de rapprocher les requêtes qui ont échoué avec un serveur; et l’idempotence fournit un mécanisme à cet effet.

La plupart des bibliothèques clients peuvent générer des clés d’idempotence et relancer des requêtes automatiquement, mais vous devez les configurer en conséquence. Pour exercer un contrôle plus précis des relances, générez des clés d’idempotence et écrivez votre propre logique pour les relances.

Requêtes GET et DELETE

L’API Stripe garantit l’idempotence des requêtes GET et DELETE. Vous pouvez donc toujours les relancer en toute sécurité.

Requêtes POST

L’inclusion d’une clé d’idempotence rend les requêtes POST idempotentes, ce qui incite l’API à effectuer l’enregistrement requis pour éviter les opérations en double. Les clients peuvent relancer en toute sécurité les requêtes qui incluent une clé d’idempotence, à condition que la deuxième requête soit effectuée dans un délai de 24 heures suivant la réception de la clé (les clés expirent du système après 24 heures). Par exemple, si une requête de création d’un objet ne répond pas en raison d’une erreur de connexion réseau, un client peut relancer la requête avec la même clé d’idempotence pour garantir qu’aucun autre objet ne sera créé.

Envoi d’une clé 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 envoyées à l’API Stripe. La plupart des bibliothèques client officielles peuvent les envoyer automatiquement, à condition qu’elles soient configurées pour envoyer des relances.

Si vous choisissez d’envoyer manuellement des clés d’idempotence, assurez-vous que les jetons utilisés soient suffisamment distinctifs pour identifier sans ambiguïté toutes les opérations effectuées sur votre compte au cours des dernières 24 heures au moins. Il existe deux stratégies courantes pour générer des clés d’idempotence :

• Utiliser un algorithme pouvant générer un jeton de manière suffisamment aléatoire, par exemple UUID v4.
• Obtenez la clé d’un objet lié à l’utilisateur, par exemple un ID de 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.

En-tête Stripe-Should-Retry

Une bibliothèque client ne peut pas toujours déterminer avec certitude si elle doit effectuer une relance uniquement sur la 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 la relance de la requête.

• Lorsque l’en-tête Stripe-Should-Retry est 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éfinie à 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éfinie dans la réponse, cela signifie que l’API ne peut pas déterminer si elle peut ou non relancer la requête. Les clients doivent s’appuyer sur d’autres propriétés de la réponse (comme le code d’état) pour prendre une décision.

Les mécanismes de relances de requête intégrés aux bibliothèques client de Stripe respectent automatiquement Stripe-Should-Retry. Si vous utilisez l’un d’elles, vous n’aurez aucune gestion manuelle à faire.

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