Idempotence et reprises
Une clé par opération métier
Section intitulée « Une clé par opération métier »Idempotency-Key est obligatoire pour créer un message ou un lot. Utilisez entre 1 et 128 caractères ASCII visibles.
Choisissez une valeur stable liée à votre opération : un rappel de rendez-vous, par exemple, doit conserver sa clé lors d’une reprise réseau.
La portée associe l’organisation, la ressource et la valeur de la clé. Une rotation de clé API ne crée pas une nouvelle opération d’idempotence dans la même organisation.
Réutiliser exactement la requête
Section intitulée « Réutiliser exactement la requête »Défilement horizontal si nécessaire. Au clavier : Tab, puis les flèches gauche et droite.
| Situation | Réaction |
|---|---|
| Même clé et même contenu déjà traité | La réponse initiale est rejouée, sauf après l’effacement décrit ci-dessous. |
| Même requête de message après effacement de ses données personnelles | HTTP 410 personal_data_erased ; arrêter les reprises et conserver la clé. |
| Même clé avec un contenu différent | Conflit HTTP 409 ; corrigez votre suivi métier. |
| Même opération encore en cours | Conflit HTTP 409 ; attendez avant de reprendre. |
| Réponse réseau perdue | Reprenez la même clé et le même corps. |
| Résultat fournisseur incertain | Consultez le message et sollicitez l’assistance si nécessaire. |
Conservez les valeurs envoyées, y compris le nom d’expéditeur et la date. Ne modifiez pas le texte ou le destinataire lors d’une reprise.
Conserver l’historique
Section intitulée « Conserver l’historique »Les clés d’idempotence v2 sont durables. Il n’existe pas de règle publique permettant de réutiliser une ancienne clé après 24 heures. Utilisez une nouvelle clé uniquement pour une nouvelle opération métier volontaire.
L’idempotence protège la soumission à l’API. Elle ne promet pas une livraison « exactement une fois » par tous les opérateurs.
Après l’effacement des données d’un message
Section intitulée « Après l’effacement des données d’un message »Après un effacement ciblé validé et exécuté pour un message dont le traitement est terminé, rejouer POST /api/sms/v2/messages/ avec sa clé et son contenu d’origine renvoie 410 avec error.code: personal_data_erased. Cette réponse remplace le résultat de création mémorisé. Elle ne déclenche aucun nouvel envoi ni mouvement de crédits.
Arrêtez les reprises de cette opération et conservez sa clé dans votre suivi. Ne renvoyez pas le message avec une nouvelle clé pour contourner l’effacement. Un contenu différent avec la même clé reste un conflit 409 idempotency_conflict, y compris après l’effacement.
Ce cas concerne le rejeu de création d’un message individuel. L’identifiant, le statut et le nombre de segments restent consultables ; les champs to et sender_name du message effacé sont des chaînes vides. Voir la réponse JSON et la conduite à tenir.
Traiter un résultat inconnu
Section intitulée « Traiter un résultat inconnu »Une erreur 502 liée à un résultat fournisseur inconnu peut inclure message_id. Conservez cet identifiant et consultez son statut.
Le fournisseur peut avoir accepté le SMS malgré la rupture de communication.
N’envoyez pas automatiquement le même texte avec une nouvelle clé : cela pourrait créer un second SMS. Ne renvoyez jamais un message uniquement pour corriger son accusé de livraison. Voir les statuts.