Comment éviter d'envoyer le même SMS deux fois ?

Une connexion peut être interrompue après que Bird a accepté un SMS mais avant que votre application ne reçoive la réponse. Réessayer avec une nouvelle clé peut créer un second envoi car Bird traite cela comme une requête distincte.

Comment fonctionne la clé ?

Définissez un en-tête Idempotency-Key pour chaque envoi SMS prévu et réutilisez-le lorsque vous réessayez la requête identique. La garantie d'acceptation unique signifie que les nouvelles tentatives correspondantes effectuées dans les trois heures aboutissent au même envoi accepté, même si vous en avez perdu la réponse.

Par exemple, une confirmation de commande conserve la même clé après un timeout et sa nouvelle tentative. Une confirmation pour une commande différente reçoit une clé différente.

Les réponses rejouées incluent Idempotency-Replay: true, ce qui permet à vos logs de distinguer un rejeu d'une requête nouvellement traitée.

Les clés SMS sont limitées à votre espace de travail. Bird conserve les réponses complétées pendant trois heures selon son contrat d'idempotence. Passé ce délai, la même clé peut exécuter une nouvelle requête car son enregistrement de rejeu a expiré. Une nouvelle tentative un jour plus tard nécessite donc une réconciliation du résultat original avant un autre envoi.

Que me disent les réponses d'erreur ?

Le code d'erreur distingue une requête modifiée, une requête inachevée et une protection indisponible.

• 409 avec E01005 IdempotencyKeyReuse : la même clé a été utilisée pour une requête différente. Corrigez l'attribution de la clé avant de réessayer, car cette clé appartient à la requête originale. Bird compare la méthode, le endpoint, le chemin et les paramètres de requête, et le corps brut. Même un changement d'espace JSON rend la requête différente.
• 409 avec E01004 RequestInProgress : une requête concurrente avec la même clé n'est pas encore terminée. Attendez brièvement et réessayez avec la même clé et la même requête pour que la requête originale puisse aboutir.
• 503 avec E01033 IdempotencyUnavailable : la protection était indisponible avant l'exécution, cette tentative n'a donc pas été exécutée. Réessayez avec un backoff en utilisant la même clé et la même requête. Cette réponse n'établit pas le résultat d'une tentative antérieure.
• Autres réponses 5xx ou timeouts : réessayez avec un backoff en utilisant la même clé et la même requête. La garantie d'acceptation unique couvre ces nouvelles tentatives pendant trois heures. Arrêtez lorsque votre budget de nouvelles tentatives est épuisé.

L'en-tête d'idempotence préserve l'identité de la requête à travers ces nouvelles tentatives.

La clé garantit-elle zéro doublon ?

La garantie est une acceptation unique des requêtes identiques portant la même clé, dans le même espace de travail, pendant trois heures. Ces nouvelles tentatives aboutissent à un seul envoi accepté, y compris après une réponse perdue. Consultez le statut du message pour confirmer la livraison.

Après la fenêtre de conservation de trois heures, la clé originale peut identifier une nouvelle opération. Si le résultat original est inconnu, réconciliez-le avant de soumettre à nouveau.

Conservez les événements et les enregistrements d'envoi de votre application pour pouvoir réconcilier un résultat incertain avant d'envoyer à nouveau. Incluez le numéro de commande ou de référence dans le message pour que le destinataire puisse reconnaître l'événement concerné.

Qu'en est-il d'un message que le téléphone affiche deux fois ?

Une clé d'idempotence régit les nouvelles tentatives API ; elle ne contrôle pas la façon dont le téléphone du destinataire affiche un message. Une capture d'écran seule n'établit pas l'origine d'un doublon.

Comparez le log d'envoi complet de votre application avec les enregistrements de messages de Bird. Plusieurs identifiants de message acceptés peuvent établir plusieurs envois. Trouver un seul identifiant dans un log incomplet ne prouve pas que le doublon s'est produit en aval. Incluez les identifiants concernés, la destination et les horodatages lorsque vous demandez au support d'investiguer.

Que dois-je faire ?

1. Attribuez une clé à chaque envoi SMS prévu et réutilisez la requête identique pour ses nouvelles tentatives.
2. Réessayez les erreurs réseau, les timeouts et les réponses 5xx avec un backoff, en conservant la clé et la requête identique pendant trois heures.
3. Corrigez les conflits de requêtes modifiées et différez les nouvelles tentatives tant que la requête originale est encore en cours.
4. Considérez les nouvelles tentatives épuisées ou expirées comme non résolues jusqu'à ce que vous en ayez réconcilié le résultat, avant de décider si un autre envoi est approprié.