IOSOR

IOSOR Guides

Idempotence de l’API d’envoi : doublons, retries et argent

Guide développeur pour les API d’envoi prépayées — clés d’idempotence, retries sûrs, anti-doublons et corrélation lisible pour le ledger, afin qu’une erreur d’ingénierie ne devienne pas un incident financier.

Les timeouts arrivent. Les balanceurs retentent. Les clients mobiles double-tapent. Sans idempotence, un produit « envoyer une fois » devient un double débit prépayé et une UX OTP en double. Ce guide s'adresse à l'engineering et au product technique qui intègrent une API de messagerie prépayée white-label — où chaque doublon apparaît dans le wallet. IOSOR attend des intégrations money-aware : appels authentifiés, débits corrélables et erreurs client qui ne collent jamais de payloads de marques tierces.

Pourquoi les doublons deviennent des problèmes d’argent

Mode de panne L'utilisateur voit Le wallet voit
Timeout client + retry aveugle Deux OTP / deux alertes Deux débits
Handler webhook non idempotent Doubles effets de bord Confusion sur le succès
Renvoi utilisateur empilé sur auto-retry Utilisateurs agacés Unités cumulées
Pas de corrélation Tickets « ça a échoué » Lignes de ledger non appariées

La démo pardonne. La finance de prod non. À intensité prépayée, un week-end de retries aveugles devient un projet de réconciliation, pas une note de bas de page.

Des clés d’idempotence qui survivent aux retries

Un chemin d'envoi sérieux accepte une clé générée côté client qui est unique par intention métier, pas par tentative TCP. Elle doit renvoyer le même résultat accepté en replay dans une fenêtre TTL claire. Cela empêche de créer en silence un second débit pour la même intention. La clé doit être journalisée avec l'ID message et la référence prépayée. Elle doit fonctionner à travers timeouts, retries de gateway et redrives support.

Budgets de retry vs renvoi utilisateur

Les retries automatiques ont besoin d'un budget : max d'essais, backoff, et quelles classes d'erreur sont retryables. Le renvoi initié par l'utilisateur est une action produit distincte avec ses propres limites et coûts. Mélanger les deux transforme un réseau instable en incident financier. Couplez le tout avec un arrêt sur solde bas et des raisons de rejet claires pour que produit et finance partagent une seule vérité.

Checklist acheteur / engineering

  1. Sémantique de clé d'idempotence et TTL documentés.
  2. Test de replay prouvant un débit pour une intention.
  3. Budget de retry auto séparé de la logique de renvoi utilisateur.
  4. ID de corrélation entre requête, statut message et ledger prépayé.
  5. Staging qui exerce les vrais corridors — les feux verts simulés ne sont pas des lancements.
  6. Hygiène des clés et moindre privilège pour les credentials d'envoi.
  7. Gestion des codes 429 et 503 sans perdre la clé d'intention originale.
  8. Alertes automatisées pour les taux de rejet de clés en double élevés.

Drapeaux rouges

  • « Retry jusqu'au 200 » sans utiliser de clés d'idempotence.
  • Handlers webhook non idempotents déclenchant des effets de bord en double.
  • Clés secrètes ou tokens d'auth apparaissant dans les logs ou tickets support.
  • Erreurs affichant des payloads de marques tierces ou des stack traces internes aux utilisateurs.
  • Absence de monitoring sur les rejets de clés.

Commencer avec IOSOR

Dans la console d’envoi, lancez un OTP ou une alerte avec une clé d’idempotence générée côté client. Forcez un timeout client, puis rejouez la même requête dans le TTL de la clé. Ouvrez le ledger prepaid : cette intention doit montrer un débit et un message visible. Deux lignes veulent dire que la clé n’a pas survécu au retry — corrigez TTL et handler avant de laisser le corridor en Live.

À retenir — IOSOR

Faites : traitez chaque envoi comme un événement de ledger d’abord.

Ce guide vous a-t-il aidé ?

Guides associés