Guides
Idempotence
Une soumission réessayée ne doit jamais envoyer deux fois. L’en-tête Idempotency-Key est la garantie qu’apporte SMSend.
La clé est obligatoire, pas optionnelle
Soumettre un lot sans Idempotency-Key est rejeté. La rendre optionnelle ferait du chemin par défaut le chemin dangereux, et le mode de défaillance — facturer deux fois un client parce qu’une réponse s’est perdue au retour — n’est pas de ceux qu’on laisse au hasard.
L’en-tête
Choisissez une valeur propre à la soumission, et dérivez-la de quelque chose de votre propre système plutôt que de la générer au hasard. Un identifiant de commande fait l’affaire ; un nouvel UUID à chaque tentative annule tout le mécanisme, car la reprise ressemble alors à une nouvelle requête.
- Longueur maximale de la clé
- 255
- Fenêtre de rejeu
- 24 h
- Reprise d’une réservation en cours devenue obsolète après
- 300 s
- Retry-After en cas de conflit avec une requête en vol
- 5 s
- L’unicité est limitée à
- api_key_id + key
Les trois issues
Ce qui se passe lors d’une répétition dépend de deux choses : la première requête est-elle terminée, et le corps est-il identique.
Rejouer une requête terminée
Envoyez la même clé avec le même corps dans la fenêtre de 24 heures et vous récupérez la réponse d’origine — les octets stockés, pas une réponse recalculée — accompagnée d’un en-tête vous indiquant qu’il s’agit d’un rejeu. Rien n’est envoyé une seconde fois et rien n’est refacturé.
Réutiliser une clé pour une autre requête
La même clé avec un corps différent est un conflit, pas un rejeu. Cela attrape le bogue où une clé est dérivée de quelque chose d’insuffisamment spécifique et où deux lots réellement différents entrent en collision.
Réessayer pendant que la première tentative tourne encore
Si la requête d’origine n’est pas terminée, la reprise est refusée avec une erreur réessayable et un Retry-After. Attendez et recommencez — la réservation est libérée dès que la première tentative s’achève.
Comment le corps est comparé
L’empreinte est un hachage de la méthode, du chemin et de la charge utile dont les clés d’objet sont triées récursivement. Trier les clés signifie qu’un client dont la bibliothèque JSON sérialise les champs dans un autre ordre lors de la reprise produit tout de même la même empreinte.
L’ordre des tableaux est significatif et n’est pas normalisé. Une liste recipients dans un ordre différent est une requête réellement différente et sera rejetée comme une réutilisation — ce qui est correct, puisqu’elle enverrait à un autre ensemble de personnes, dans un autre ordre.
Une soumission refusée libère la clé
Si un lot est refusé — pour fonds insuffisants, par exemple — l’enregistrement d’idempotence est supprimé plutôt que conservé. Vous pouvez donc recharger le portefeuille et réessayer la requête identique avec la clé identique, ce qui est exactement ce que veut l’appelant et ce qu’une implémentation naïve interdirait pendant 24 heures.
Une réservation laissée en cours plus de cinq minutes est reprise par la tentative suivante, si bien qu’un worker planté en pleine requête ne peut pas empoisonner une clé jusqu’à l’expiration de la fenêtre.