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é ?

Vous définissez un en-tête Idempotency-Key pour chaque envoi SMS prévu et le réutilisez lorsque vous réessayez la requête identique. Quand Bird conserve la réponse originale, une nouvelle tentative correspondante renvoie cette réponse sans exécuter l'envoi à nouveau.

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. Le verrou en vol expire en 30 secondes. L'expiration n'établit pas si l'envoi original a pris effet.
• 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. Bird ne conserve pas les réponses 5xx. Une nouvelle tentative rejoue une réponse réussie conservée ou peut s'exécuter à nouveau si aucune réponse n'a été conservée.

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 clé réduit les envois en double, mais elle ne garantit pas une exécution unique.

Un envoi peut prendre effet avant que Bird ne conserve sa réponse. Si la conservation de la réponse échoue ou si le verrou en vol expire, une nouvelle tentative peut exécuter l'envoi à nouveau. La fenêtre de conservation de trois heures limite également la protection par rejeu.

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é pour maintenir toute protection par rejeu disponible.
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. Réconciliez les envois incertains, y compris ceux au-delà de la fenêtre de rejeu de trois heures, avant de décider si un autre envoi est approprié.