En bref

L’idempotence, les nouvelles tentatives et le rapprochement ne sont pas trois fonctionnalités indépendantes. Ils forment une seule chaîne de traitement des défaillances : des identifiants stables reconnaissent une même intention métier ; la sémantique d’idempotence détermine si la répétition est sûre ; des nouvelles tentatives limitées traitent les pannes transitoires ; le rapprochement compare les demandes au résultat financier final ; et l’escalade manuelle traite les états que l’automatisation ne peut toujours pas résoudre.

L’hypothèse la plus dangereuse est : « un délai d’attente signifie un échec, donc renvoyons la demande ». Un serveur peut achever une demande même si sa réponse se perd pendant le transport. L’appelant se trouve alors dans un état inconnu, et non face à un échec confirmé. Sans sémantique explicite d’idempotence ou de consultation, une nouvelle tentative automatique peut créer une session, un transfert ou une écriture de grand livre en double.

Cinq concepts à distinguer

Concept Définition pratique Ce qu’il ne garantit pas à lui seul
Identifiant stable Une valeur durable qui corrèle la même demande, transaction, manche ou pari La présence d’un ID ne prouve pas la déduplication côté serveur
Idempotence La répétition d’une même intention métier est censée avoir le même effet final que son traitement unique Les réponses ne doivent pas forcément être textuellement identiques, et la demande peut toujours échouer
Nouvelle tentative Une autre tentative dans des conditions définies, avec une limite de tentatives et un budget de temps Une erreur permanente ne devient pas un succès, et une nouvelle tentative ne remplace pas la consultation de l’état
Rapprochement La comparaison de l’intention de demande, du résultat métier, des enregistrements de transaction ou de manche, et de l’effet sur le grand livre Il ne décide pas automatiquement de chaque compensation
Escalade manuelle Une personne autorisée enquête et décide lorsque l’automatisation ne peut pas conclure de façon sûre Le jugement humain ne peut pas compenser l’absence de journaux ou de définitions de protocole

Les méthodes HTTP ne déterminent pas la sémantique métier du projet. La RFC 9110 définit PUT, DELETE et les méthodes sûres comme idempotentes, et invite les clients à ne pas relancer automatiquement des demandes non idempotentes, sauf si leur véritable sémantique est connue comme étant idempotente ou si le client peut établir que la demande initiale n’a pas été appliquée. Les appels de plateforme présentés dans la référence API publique utilisent POST ; un comportement sûr de nouvelle tentative ne peut donc pas être déduit de la seule méthode HTTP.

1. Identifiants stables : distinguer la traçabilité de l’identité métier

Une conception fiable requiert normalement au moins deux catégories d’identifiants :

  • ID de traçage de la demande : corrèle une tentative de transport avec les journaux, une réponse et les éléments de diagnostic.
  • ID de transaction métier : identifie une intention métier et corrèle les transferts, mouvements de grand livre, manches ou paris.

La référence API publique présente reqTraceId et, dans certains flux de transaction, des champs tels que merchantTransactionId, transactionId, roundId et betId. Elle décrit merchantTransactionId comme un identifiant unique de transaction du marchand pouvant faciliter le rapprochement.

Ces champs donnent des indications de traçabilité. Ils n’établissent pas des comportements non confirmés, par exemple si chaque opération est dédupliquée, le périmètre et la période de conservation de la déduplication, ce qui se produit lorsque le même ID arrive avec des paramètres différents, ou si une répétition renvoie le résultat initial. Ces sémantiques exigent un protocole formel et des tests dans l’environnement applicable.

Le projet IETF draft-ietf-httpapi-idempotency-key-header-07 a proposé l’en-tête Idempotency-Key. Au 9 août 2026, cette version était expirée et archivée, et n’était pas devenue une RFC. Elle ne peut être considérée que comme un élément historique de conception — pas comme une norme en vigueur, un protocole AG, ni la preuve qu’AG prend en charge cet en-tête.

2. Nouvelles tentatives : ne faire des tentatives limitées que pour les opérations et pannes sûres

Une nouvelle tentative automatique doit remplir les deux conditions suivantes : la panne est classée comme transitoire, et la répétition est sûre selon le protocole applicable.

Scénario Principe par défaut Condition préalable à une nouvelle tentative automatique
Consultation ou liste en lecture seule Une nouvelle tentative limitée peut être envisagée Le protocole confirme l’absence d’effet de bord et l’échec est transitoire
Création de session Ne pas recréer uniquement à cause d’un délai d’attente Idempotence explicite, ou consultation de la session existante par son identifiant initial
Mutation de portefeuille ou transfert Vérifier d’abord l’état ou effectuer un rapprochement par défaut L’ID métier, le périmètre d’idempotence et le comportement de réponse aux doublons sont confirmés
Traitement d’un rappel Le consommateur doit détecter les événements répétés Les deux parties conviennent de l’ID stable d’événement ou de transaction utilisé pour la déduplication
Erreur de paramètre, d’autorisation ou de signature Ne pas relancer automatiquement la même demande Corriger le paramètre, l’accès, l’horloge ou l’identifiant d’accès, puis prendre une nouvelle décision
Délai d’attente ou déconnexion Marquer le résultat comme inconnu Consulter d’abord par l’ID initial ; ne relancer que lorsque la sémantique sûre est établie

Les nouvelles tentatives nécessitent un délai d’attente par tentative, un nombre maximal de tentatives, un budget de temps total et des conditions d’arrêt. Cet article ne prescrit pas de valeurs numériques : elles dépendent de la sémantique de l’API, des contraintes amont, du risque métier et de l’accord entre les parties.

3. Backoff exponentiel et gigue : éviter une pression synchronisée

Lorsqu’une panne transitoire peut être traitée sans risque par une nouvelle tentative, un backoff exponentiel limité avec gigue aléatoire peut répartir les tentatives dans le temps. Conceptuellement, le délai augmente à chaque tentative jusqu’à un maximum, tandis que la gigue évite que de nombreux clients ne relancent au même instant.

AWS et Google documentent tous deux l’intérêt du backoff et de la gigue. Google précise également que l’éligibilité à une nouvelle tentative dépend du caractère relançable de l’échec et de l’idempotence de l’opération. Un algorithme de backoff ne peut pas rendre sûre une écriture non idempotente et ne remplace pas un budget global de nouvelles tentatives.

Évitez les anti-modèles suivants :

  • des boucles de nouvelles tentatives immédiates ou sans limite ;
  • une politique unique de nouvelles tentatives pour chaque erreur HTTP et métier ;
  • des nouvelles tentatives aux couches passerelle, SDK, service et file d’attente qui se multiplient entre elles ;
  • la génération d’un nouvel ID de transaction métier à chaque tentative, empêchant de reconnaître l’intention initiale ;
  • la journalisation de clés, d’identifiants d’accès complets ou de données sensibles inutiles pendant les nouvelles tentatives ;
  • la poursuite indéfinie des nouvelles tentatives automatisées après des échecs répétés.

La RFC 9110 exige également de la prudence avec les nouvelles tentatives automatisées ; un échec répété ne doit pas devenir une répétition sans limite.

4. État inconnu : ne pas rebaptiser l’incertitude en échec

Lorsqu’une demande a quitté l’appelant mais qu’aucun résultat métier complet n’est renvoyé, utilisez un état UNKNOWN distinct. Un flux neutre vis-à-vis du protocole peut être représenté ainsi :

NEW -> SENT -> CONFIRMED_SUCCESS
            -> CONFIRMED_FAILURE
            -> UNKNOWN -> QUERY_OR_RECONCILE -> CONFIRMED_SUCCESS
                                           -> CONFIRMED_FAILURE
                                           -> MANUAL_REVIEW

Dans l’état UNKNOWN, consultez les résultats existants, les enregistrements de transaction ou les mouvements de grand livre à l’aide de l’ID de demande ou de transaction métier d’origine. Si le protocole ne fournit pas de voie de consultation faisant autorité, arrêtez les actions automatisées susceptibles de dupliquer des effets, conservez le contexte et escaladez. Ne supposez pas un échec.

Les libellés d’état, l’API de consultation et les états terminaux doivent suivre le protocole des parties. Ce diagramme est une méthode de conception ; il n’affirme pas qu’AG met en œuvre ces états exacts.

5. Rapprochement : utiliser plusieurs enregistrements pour établir l’effet final

Le rapprochement ne se limite pas à comparer deux valeurs de solde. Pour les flux de portefeuille, de pari ou de gain, corrélez au minimum :

  • l’intention métier initiale et l’ID de traçage de la demande ;
  • l’ID de transaction métier du marchand ou de la plateforme ;
  • les identifiants de transaction, de manche et de pari de la contrepartie ;
  • le montant, la devise, le sens et l’interprétation du temps ;
  • le résultat métier de l’API et les enregistrements ultérieurs ;
  • le mouvement de grand livre, le solde actuel et l’état final du traitement.

Les résultats utiles comprennent : rapproché, échec confirmé, doublon, écart de montant ou de devise, enregistrement manquant et état inconnu. Chaque écart nécessite un responsable prédéfini, un ensemble de preuves, une autorité de compensation et une condition de clôture. Ne renvoyez pas la mutation financière d’origine en remplacement d’un rapprochement.

La fréquence, la conservation et la tolérance dépendent du risque métier, du volume, du modèle de portefeuille et du contrat. Cet article ne fixe pas de périodes ou de seuils AG.

6. Quand l’escalade manuelle est obligatoire

Arrêtez l’automatisation et ouvrez une revue manuelle traçable lorsque l’un des cas suivants s’applique :

  • le budget limité de nouvelles tentatives est épuisé et l’état métier reste inconnu ;
  • un même ID métier apparaît avec des montants, devises, comptes ou autres paramètres critiques différents ;
  • le résultat de la demande, l’enregistrement de transaction et le mouvement de grand livre sont contradictoires ;
  • l’enregistrement faisant autorité défini par le protocole est introuvable, ou des journaux critiques sont incomplets ;
  • il existe une suspicion de débit en double, de paiement en double, d’accès non autorisé ou d’incident de sécurité ;
  • une compensation automatisée pourrait accroître l’impact financier, de conformité ou client.

Le dossier doit inclure les ID d’origine, une chronologie, les actions déjà entreprises, les preuves, l’évaluation du risque, l’approbateur et le résultat final de clôture. Les secrets et identifiants d’accès ne doivent pas figurer dans le corps des tickets.

Liste de contrôle d’implémentation sur une page

  • Définissez des ID stables distincts pour le traçage des demandes et les transactions métier.
  • Spécifiez le périmètre d’idempotence, le comportement en cas de conflit et la sémantique des réponses répétées pour chaque opération ayant des effets de bord.
  • Distinguez les erreurs transitoires, les erreurs permanentes et les états inconnus.
  • Ne faites automatiquement une nouvelle tentative que lorsque la répétition est confirmée comme sûre.
  • Définissez des délais d’attente, un budget total, un plafond de backoff exponentiel limité et une gigue pour les parcours éligibles.
  • Empêchez les nouvelles tentatives à plusieurs couches du système de se multiplier de façon inattendue.
  • Fournissez une consultation ou un rapprochement par l’ID initial pour les états inconnus.
  • Rapprochez les preuves de transaction, de manche, de montant, de devise et de grand livre.
  • Définissez les conditions d’arrêt de l’automatisation et la responsabilité de l’escalade manuelle.
  • Testez en préproduction les cas de délai d’attente, de réponse perdue, de soumission en double et d’écart d’enregistrement.

Ce qui peut actuellement être évalué sur ce site

  • La référence API publique présente des identifiants pour les demandes et certaines transactions métier, manches et paris.
  • Les notes d’interface imposent d’évaluer le résultat métier du corps de réponse plutôt que le seul statut HTTP.
  • Les consultations de portefeuille, de transaction, de manche et de pari peuvent éclairer la conception des tests de traçabilité et de rapprochement.
  • Les pages actuelles décrivent des portefeuilles unique et de transfert, mais la conception de fiabilité doit suivre le modèle de portefeuille retenu et le protocole formel.

Limites à garder à l’esprit

  • Cette page n’affirme pas que tous les points de terminaison AG en POST sont idempotents ni qu’AG prend en charge l’en-tête Idempotency-Key.
  • Elle n’invente pas le périmètre de déduplication AG, sa conservation, les réponses aux conflits, les nombres de nouvelles tentatives, les paramètres de backoff ou les calendriers de rapprochement.
  • Elle n’ajoute aucun point de terminaison de consultation, de compensation, d’état ou de production.
  • Elle ne promet ni absence de doublons, ni absence de pertes, ni cohérence absolue, ni sécurité absolue, ni performances fixes, ni SLA.
  • Les exemples d’API publics ne constituent pas un protocole de production, une garantie d’exécution ou un enregistrement d’admission en production pour un projet.

FAQ

Une demande POST échouée peut-elle faire l’objet d’une nouvelle tentative automatique ?

Pas sur la seule base du mot « échouée » ou de POST. Établissez d’abord si la panne est transitoire, si la demande initiale a peut-être déjà produit un effet, et si le protocole formel fournit l’idempotence ou une consultation par l’ID initial. Sinon, l’opération relève du traitement des états inconnus et du rapprochement.

Un délai d’attente signifie-t-il que la transaction a échoué ?

Non. Un délai d’attente signifie seulement que l’appelant n’a pas reçu de résultat complet à temps. Le serveur peut ne pas avoir démarré, être encore en cours de traitement, ou avoir réussi ou échoué. Consultez ou rapprochez à l’aide de l’ID métier d’origine.

Un ID de transaction unique prouve-t-il l’idempotence ?

Non. C’est une base importante pour reconnaître une intention métier, mais le protocole doit aussi définir la manière dont le service le stocke et le compare, son périmètre et sa durée de vie, les conflits de paramètres et le résultat renvoyé lors d’une répétition.

Une nouvelle tentative doit-elle recevoir un nouvel ID de demande ?

Cela dépend de la manière dont le protocole distingue une intention métier d’une tentative de transport. L’ID de transaction métier doit généralement rester stable. Le fait de réutiliser ou de dériver un ID de traçage doit être explicite dans le contrat d’interface, et ne pas être déduit de cet article ou d’un nom de champ.

Lectures associées et prochaines étapes

Pour concevoir la fiabilité d’une intégration spécifique, utilisez la section « Contactez-nous » afin de fournir le modèle de portefeuille, le sens des appels, les opérations métier critiques et les capacités de rapprochement actuelles. AG pourra alors confirmer les identifiants, la sémantique de consultation, les limites des nouvelles tentatives et la responsabilité de l’escalade au regard du protocole formel, sans promettre à l’avance un comportement de production.

Sources et périmètre

Les champs pertinents et le périmètre de la page figurent dans la référence API publique, la présentation de l’API Slots et le processus d’intégration. L’implémentation doit toujours suivre le protocole et le comportement observé dans l’environnement convenu par les deux parties.

Sources générales sur la fiabilité :

Ces sources expliquent des modèles généraux. Elles ne confirment pas qu’AG utilise un algorithme, des paramètres ou un en-tête d’un fournisseur. Les responsables de l’API, du portefeuille, des SRE, de la sécurité et du rapprochement doivent examiner la sémantique du projet et les exemples de champs.

Transformer ce guide en plan de projet ?

Ce contenu aide à préparer une évaluation. Il ne remplace pas la confirmation technique, contractuelle, de certification ou de droit local applicable au projet.

Contacter AG GAME