Résumé

  • Pour un POST en API v1, Stripe mémorise le statut et le corps de la première requête après le début de son exécution, y compris un 500. La même clé redonne cette réponse tant qu’elle reste conservée.
  • Un 500 laisse l’issue indéterminée. Stripe peut rapprocher l’opération et envoyer un webhook pour un objet créé sans changer la réponse mémorisée. L’API v2 suit une autre règle de nouvelle tentative.

Le rouge n’est pas une horloge du traitement

Une application reçoit 500 et renvoie la demande avec la même clé. Le deuxième 500 ressemble à une nouvelle panne. Pour l’API v1 de Stripe, il peut n’être que le premier reçu remis une seconde fois. Le résultat est mémorisé dès que l’exécution du point de terminaison commence. L’en-tête Idempotent-Replayed: true permet de reconnaître cette répétition. Compter deux réponses rouges comme deux opérations échouées mélange la preuve de transport avec le résultat économique.

Stripe prévient que le 500 est une issue indéterminée: un effet a pu se produire. Pendant la reprise d’un incident, l’entreprise tente de rapprocher les opérations et peut envoyer des événements webhook pour les objets créés. Le cache ne réécrit pas son reçu quand ce travail avance. Le rapprochement, de son côté, n’aboutit pas nécessairement. L’équipe a donc besoin d’un autre registre que la réponse HTTP.

Ce registre se construit avant l’appel: un identifiant local de l’opération inscrit dans les métadonnées de l’objet. Après le 500, l’équipe peut rechercher l’objet, examiner la demande dans le Dashboard et rapprocher les webhooks vérifiés de son identifiant. Une nouvelle clé d’idempotence utilisée alors que l’issue reste inconnue risque de lancer une deuxième opération. Le service client et la comptabilité doivent regarder le même identifiant plutôt que débattre du nombre de tentatives.

L’API v2 change la mécanique: Stripe indique qu’une nouvelle tentative ne répète pas une réussite et cherche, si possible, à terminer un travail échoué ou partiel avec une réponse actualisée. Une migration de v1 vers v2 modifie donc le sens du verbe « réessayer ». Le contrôle le plus utile n’est pas le nombre de clics sur Réessayer, mais la version appelée et l’état durable de l’objet.

Sources