Stripe se souvient de votre requête quand la réponse disparaît

Ce que couvre cette vidéo

• L'idempotence concerne l'effet voulu de la répétition d'une opération. L'API Stripe v1 ajoute un contrat documenté de relecture de réponse enregistrée.
• Une nouvelle tentative de la même action logique utilise la même clé et les mêmes paramètres. Persistez la clé d'opération à travers des appels SDK ou des redémarrages d'application distincts ; une action véritablement nouvelle nécessite sa propre clé.
• Après le début de l'exécution du point de terminaison, l'API Stripe v1 enregistre l'état et le corps de la première requête, y compris les erreurs 500, et renvoie cette réponse enregistrée lors des nouvelles tentatives.
• Des paramètres modifiés avec la même clé produisent une non-concordance. Les échecs de validation et les conflits d'exécution concurrents n'enregistrent aucun résultat idempotent pour cette tentative et peuvent être réessayés.
• Stripe conserve les clés de l'API v1 pendant au moins 24 heures et peut les supprimer ensuite. Limitez les nouvelles tentatives réseau non résolues aux premières 24 heures, puis arrêtez-vous et réconciliez avant de répéter l'opération.
• Une erreur 500 mise en cache peut continuer à être rejouée après le rétablissement de la connectivité. L'opération d'origine peut avoir des effets secondaires ; utilisez l'objet pertinent, la requête du tableau de bord et les webhooks pour établir son résultat.
• L'API v2 utilise une sémantique de relecture différente. Une clé n'établit pas une livraison exactement une fois universelle pour le courrier électronique, l'inventaire et chaque opération de base de données locale.

Transcription traduite

Traduit de la narration originale en anglais. L'audio et les sous-titres disponibles sont gérés par YouTube.

Un délai d'attente a-t-il annulé votre paiement ?

0:00 Vous pensez qu'un délai d'attente signifie que votre paiement a échoué. Le serveur peut terminer pendant que la réponse disparaît, laissant votre paiement afficher absolument rien avec confiance. Pourquoi une nouvelle tentative peut-elle facturer à nouveau ? Comment Stripe se souvient-il d'une tentative ? Quand devriez-vous arrêter de retenter ? Et gardez un détail désagréable à l'esprit. Une erreur mémorisée peut survivre au problème réseau.

0:17 Nous y reviendrons. Ceci est The Daily Diff, sous le capot.

Qu'identifie une clé d'idempotence ?

0:21 L'idempotence signifie que répéter une opération a le même effet voulu que de le faire une seule fois. Une clé d'idempotence étiquette une action logique. La version un de l'API de Stripe reconnaît cette étiquette lors des nouvelles tentatives et rejoue une réponse enregistrée. Imaginez l'achat d'un café. Stripe complète votre demande de paiement, et la réponse se perd en retournant chez vous. Le client voit un cercle de chargement. Leur banque peut avoir une interprétation plus excitante. Une demande de création non protégée peut répéter l'effet secondaire.

Comment la même clé sécurise-t-elle une nouvelle tentative ?

0:45 Joignez une clé unique avant la première tentative et conservez-la pour les nouvelles tentatives. Si votre application redémarre, conservez cette clé avec l'opération dans vos enregistrements. Pour l'API version un de Stripe, une fois l'exécution du point de terminaison commencée, l'état et le corps de la première requête sont enregistrés. Envoyez la même clé et les mêmes paramètres à nouveau, et Stripe renvoie la réponse enregistrée. Le café reste en place tandis que son reçu voyage à nouveau.

Qu'est-ce que Stripe enregistre exactement ?

1:07 Voici la formulation réelle de Stripe. Les nouvelles tentatives avec la même clé renvoient la réponse enregistrée, y compris les erreurs cinq cents. La documentation fait plus de travail que votre assistant de réessai nommé avec optimisme. Le client tape à nouveau. Votre application décide si cela reprend l'achat en attente ou en démarre un autre. Un café véritablement nouveau obtient une nouvelle clé. Une nouvelle clé pour chaque nouvelle tentative réseau annule la protection.

1:27 Des paramètres différents avec la même clé déclenchent une non-concordance.

Que se passe-t-il lorsque la requête change ?

1:30 Si les paramètres échouent à la validation, ou si une autre requête avec cette clé est toujours en cours d'exécution, Stripe n'enregistre aucun résultat idempotent pour cette tentative. Ces requêtes peuvent être réessayées. Une requête en cours de course obtient un conflit. Ce sont les règles de la version un. La version deux se comporte différemment. Un en-tête ne peut pas promettre une livraison exactement une fois à travers votre système. Le courrier électronique, l'inventaire et votre base de données ont chacun besoin d'une gestion des échecs.

1:52 La clé protège l'opération dans son champ d'application documenté. Stripe conserve les clés de la version un pendant au moins vingt-quatre heures et peut les supprimer

Combien de temps le résultat mémorisé est-il sûr à retenter ?

1:59 ensuite. Une clé supprimée peut exécuter une nouvelle requête. Gardez les nouvelles tentatives non résolues dans les vingt-quatre premières heures. Au-delà, arrêtez-vous et réconciliez le résultat original. Utilisez le backoff exponentiel et le jitter pour donner au serveur un peu de répit. Sinon, les nouvelles tentatives forment une file d'attente devant un café en feu. Les bibliothèques de Stripe gèrent les nouvelles tentatives, mais vérifiez les paramètres par défaut de votre bibliothèque. Cette erreur persistante est le piège.

Pourquoi une erreur mémorisée peut-elle revenir sans cesse ?

2:20 Une réponse cinq cents mise en cache continue de rejouer après le rétablissement de la connectivité. L'opération d'origine peut avoir produit des effets secondaires. Résolvez son résultat en utilisant les objets, le tableau de bord et les webhooks. Une nouvelle clé peut répéter l'action. Si vous préférez lire ceci plutôt que de m'entendre le dire, le diff atterrit dans votre boîte de réception chaque matin, gratuitement sur thedailydiff.dev, lien ci-dessous.

Expédieriez-vous un bouton de réessai avec ce contrat ?

2:39 Verdict, sous le capot. Expédiez-le. J'expédierais des clés stables avec des nouvelles tentatives limitées et une réconciliation, pour que les clients obtiennent du café sans financer votre éducation aux systèmes distribués. Et c'est le diff pour aujourd'hui. Je suis Niko d'Axrisi. Fusionnez de manière responsable.

Sources

1. Idempotent requestsStripe Docs
2. Designing robust and predictable APIs with idempotencyStripe Engineering — Brandur Leach
3. Advanced error handlingStripe Docs
4. HTTP Semantics — RFC 9110 §9.2.2 Idempotent MethodsIETF / RFC Editor