Doublons de commandes avec l'API : causes et protection

Pourquoi les doublons apparaissent après une seule action

Le propriétaire d'un panneau peut cliquer une seule fois sur un bouton et voir plusieurs commandes identiques : abonnés, vues, réactions ou autre service. En général, le problème ne vient pas du clic lui-même, mais de la chaîne entre le client, l'API, la base de données et le fournisseur.

Du point de vue du serveur, « une requête » n'est pas toujours unique. Le client a pu ne pas recevoir de réponse, renvoyer l'envoi, alors que la première opération avait déjà été enregistrée. Parfois, la commande est créée une seule fois dans la base du panneau, mais part deux fois chez le fournisseur. Ce sont des scénarios différents, et ils se corrigent de manières différentes.

Un délai d'attente ne signifie pas que la commande n'a pas été créée

La cause la plus fréquente : le client attend une réponse pendant un temps limité. Le serveur reçoit la requête, crée la commande, mais répond après le délai d'attente défini. Le client considère l'opération comme échouée et la renvoie.

Résultat : la première commande est déjà dans la base, et la seconde requête en crée une autre. Cela se produit particulièrement souvent en cas de réponse lente d'une API externe, de file d'attente surchargée ou de connexion instable entre les services.

Un délai d'attente indique seulement l'absence de réponse, pas l'absence de traitement de la requête.

Répétitions automatiques côté client

Les bibliothèques de requêtes HTTP, les tâches en arrière-plan et les services d'intégration répètent souvent la requête automatiquement. Le motif peut être une erreur de connexion, un code de réponse du serveur, une coupure réseau ou une réponse trop longue.

La répétition en soi est utile : elle réduit le nombre de commandes perdues lors de pannes temporaires. L'inconvénient de cette approche : sans protection contre le retraitement, elle transforme toute instabilité réseau en doublons.

• la répétition peut être lancée dans le code du site ou du bot ;
• la tâche peut être relancée par la file d'attente ;
• la requête peut être répétée par un proxy ou un module d'intégration ;
• l'opérateur peut renvoyer manuellement la commande après une erreur.

Une requête répétée arrive avant la première réponse

Parfois, deux requêtes identiques atteignent réellement l'API presque simultanément. Par exemple, l'utilisateur a soumis le formulaire deux fois, le frontend n'a pas bloqué le bouton, ou une tâche en arrière-plan a redémarré avant la fin de la première.

Si le gestionnaire vérifie d'abord l'existence de la commande, puis la crée, deux opérations parallèles peuvent passer la vérification en même temps. Chacune verra que la commande n'existe pas encore, et chacune ajoutera un nouvel enregistrement.

Cette situation est appelée condition de course. Une simple vérification préalable dans le code ne protège pas complètement contre elle. L'inconvénient d'une vérification sans contrainte au niveau de la base : elle se casse sous charge parallèle.

La commande a été enregistrée, mais la réponse de l'API s'est perdue

La requête passe par plusieurs étapes : le serveur reçoit les données, crée l'enregistrement, place la tâche dans la file d'attente, envoie la réponse. Une panne est possible entre chacune d'elles. Par exemple, la base a déjà confirmé la création de la commande, mais la connexion a été coupée avant la transmission de la réponse au client.

Le client ne sait pas si la commande a été acceptée et répète l'opération. Une API sans mécanisme de vérification distinct perçoit la requête comme nouvelle. Dans le journal, cela ressemble souvent à un service qui aurait créé deux commandes « tout seul », alors qu'il a reçu deux appels entrants.

Clé d'idempotence pour la création de commande

Pour les opérations de création, une clé d'idempotence unique est nécessaire. Le client la génère avant le premier envoi et la transmet avec les paramètres de la commande. En cas de répétition due à un délai d'attente ou à une erreur, la même clé est utilisée.

L'API enregistre la clé avec le résultat du traitement. Si une requête avec une clé déjà connue arrive, le serveur ne crée pas de nouvelle commande, mais renvoie le résultat du premier appel : l'identifiant de la commande, son statut ou l'erreur précédemment générée.

Une clé doit correspondre à une opération métier, et non à une connexion HTTP.

L'inconvénient de la méthode : les clés doivent être stockées, nettoyées selon des règles et vérifiées côté API. Si une nouvelle clé est générée à chaque répétition, la protection ne fonctionnera pas. Si une même clé est utilisée pour différentes commandes, une partie des nouvelles opérations sera rejetée à tort.

L'unicité doit être contrôlée par la base de données

L'idempotence gagne à être complétée par une contrainte d'unicité dans la base. Pour cela, on choisit une combinaison qui décrit sans ambiguïté la commande : identifiant interne du client, clé d'idempotence, type de service et autres champs nécessaires.

La base de données doit rejeter le second enregistrement, même si deux gestionnaires sont arrivés à la création simultanément. Après le conflit, l'API renvoie la commande existante, et non une erreur sans explication.

L'inconvénient d'une contrainte d'unicité stricte : elle ne peut pas être construite uniquement sur un lien ou un username. Un client peut délibérément commander un même service sur la même chaîne plusieurs fois. Une contrainte trop large bloquerait des achats répétés normaux.

La file d'attente peut livrer une tâche plus d'une fois

Les files d'attente de tâches fonctionnent souvent selon le principe « livraison au moins une fois ». Si un worker a traité la tâche mais n'a pas eu le temps de confirmer son exécution, la file peut remettre la même tâche à un autre worker.

Pour la file, c'est une manière normale de ne pas perdre la tâche. Pour la création de commande sans idempotence, c'est une source de doublons. L'identifiant de la tâche ou une clé d'opération distincte doit être transmis jusqu'au gestionnaire final, y compris au module d'envoi de la commande au fournisseur.

L'inconvénient de désactiver la livraison répétée : en cas de chute d'un worker, une partie des commandes peut disparaître. Il est plus sûr d'accepter les répétitions possibles et de rendre le gestionnaire résistant à celles-ci.

Les doublons apparaissent entre le panneau et le fournisseur

La commande interne peut être créée une seule fois, mais la requête vers l'API externe envoyée deux fois. La cause est la même : le panneau n'a pas reçu de réponse du fournisseur et a décidé de répéter l'envoi. Si le fournisseur a eu le temps d'accepter la première requête, deux demandes identiques apparaîtront de son côté.

Une liaison distincte entre la commande interne et la commande externe est nécessaire : identifiant d'envoi, clé d'idempotence ou réponse du fournisseur enregistrée. On ne peut pas considérer que la protection à l'entrée de son propre panneau protégera automatiquement les appels sortants.

L'inconvénient de la vérification avec une API tierce : tous les fournisseurs ne prennent pas en charge la recherche par clé externe. Il faut alors enregistrer les tentatives d'envoi et traiter séparément les statuts indéterminés.

Un webhook ne doit pas créer une nouvelle commande

Les webhooks signalent des changements : commande acceptée, lancée, exécutée, annulée ou nécessitant une vérification. L'erreur survient lorsque le gestionnaire de webhook perçoit la notification comme une commande de recréation de la commande.

Un même webhook peut arriver à nouveau. L'expéditeur répète la livraison s'il n'a pas reçu de confirmation, et les notifications arrivent parfois dans le désordre. Le gestionnaire doit retrouver la commande existante par identifiant externe et mettre à jour le statut.

L'inconvénient de traiter les webhooks uniquement selon l'heure de réception : une notification tardive peut écraser le statut actuel par un statut obsolète. Des identifiants d'événement, une version de statut ou des règles de transition claires sont nécessaires.

Quels enregistrements aident à trouver la source des doublons

Pour l'investigation, voir seulement deux numéros de commande ne suffit pas. Il faut des données sur chaque étape du traitement : heure de la requête, clé d'idempotence, identifiant du client, paramètres de la commande, numéro de la tâche en arrière-plan, réponse de l'API externe et tentatives de renvoi.

• comparez les doublons par clé d'opération, et pas seulement par lien ;
• vérifiez si des requêtes identiques figuraient dans le journal de l'API entrante ;
• regardez si la tâche a été répétée dans la file d'attente ;
• séparez la création de la commande interne de l'envoi au fournisseur ;
• enregistrez l'identifiant externe de la demande immédiatement après réception de la réponse.

L'inconvénient de journaux trop courts : la source du problème disparaît avant qu'on ait pu l'analyser. L'inconvénient d'une journalisation excessive : des tokens, des données personnelles et d'autres champs sensibles peuvent s'y retrouver, il faut donc les masquer.

Comment traiter un résultat de requête indéterminé

Après un délai d'attente, on ne peut pas recréer immédiatement la commande avec de nouvelles données. D'abord, l'API doit vérifier l'opération par clé d'idempotence ou identifiant client. Si la commande est trouvée, son état actuel est renvoyé. Si le traitement est encore en cours, le client reçoit un statut d'attente.

1. Créer une clé d'opération avant la première requête.
2. Envoyer la même clé à chaque répétition.
3. Enregistrer la clé et la commande dans une même opération de base de données protégée.
4. Transmettre l'identifiant d'opération à la file d'attente et à l'API externe.
5. Renvoyer la commande précédemment créée lors d'un nouvel appel.

Un tel scénario nécessite des modifications de l'API et de l'intégration client. Son inconvénient : un débogage plus complexe et davantage d'états de commande, mais la livraison répétée d'une requête cesse de signifier automatiquement un nouvel achat.