Une boucle de nouvelles tentatives aveugle est une cause fréquente de ce phénomène : au lieu de survivre à une panne passagère, l'intégration avec l'API d'un tiers l'aggrave. Elle continue de marteler une clé déjà invalide, consomme la limite de requêtes sur des appels voués à l'échec ou, pire encore, débite une seconde fois le même achat. La bonne approche ne commence pas par la pause entre les tentatives, mais par la classification de la cause : toutes les erreurs ne méritent pas d'être réessayées, et toutes les nouvelles tentatives ne sont pas sans risque.

Trois catégories d'erreurs d'API

Les erreurs temporaires ne tiennent pas au contenu de la requête : coupure réseau, délai de connexion dépassé, surcharge passagère du service chez le fournisseur. La même requête avec les mêmes paramètres, envoyée quelques secondes plus tard, passera normalement, car le défaut venait du canal ou du moment, et non de la requête elle-même.

Les erreurs permanentes sont le cas inverse : clé d'accès incorrecte, paramètre invalide, absence de droits sur l'opération. Un tel appel échouera de la même manière à la première tentative comme à la centième, car la cause se trouve dans la requête elle-même ou dans la configuration du compte. Réessayer sans corriger la cause n'apporte rien d'autre qu'une ligne de plus dans le journal.

Les erreurs liées à l'argent ressemblent formellement aux erreurs temporaires : solde insuffisant, aucun numéro disponible pour le pays voulu. Une nouvelle requête peut aboutir plus tard, après un rechargement du solde ou une mise à jour du stock, mais il ne faut pas la renvoyer à l'aveugle, et encore moins l'opération de débit elle-même. Les sections suivantes expliquent pourquoi.

Ce qu'il faut réessayer, et ce qu'il ne faut pas

La règle est simple : il n'y a lieu de réessayer que ce qui peut se corriger de lui-même avec le temps. Une panne réseau, un délai dépassé, une réponse 5xx ou un signe de surcharge sont des candidats à une nouvelle tentative automatique selon un schéma de backoff. Une clé incorrecte, un paramètre erroné, un refus pour manque de droits : il est inutile de réessayer tant que la cause n'a pas été éliminée manuellement. Il faut corriger la configuration et renvoyer l'appel une seule fois, au lieu de faire tourner une boucle. Le manque de solde ou de stock doit être présenté à l'appelant comme un état à part, et la décision de réessayer revient à la logique métier ou à l'utilisateur, pas à un minuteur. L'article Activation OTP ou location de numéro détaille dans quel modèle, achat à l'unité ou location pour une durée, la pénurie de stock survient le plus souvent.

Backoff exponentiel et coût d'une nouvelle tentative aveugle

Le backoff exponentiel est une pause avant la tentative suivante qui s'allonge à chaque fois : par exemple une seconde, puis deux, quatre, huit, jusqu'à un plafond de quelques tentatives, en général trois à cinq, après lequel la boucle s'arrête et l'échec est remonté comme définitif. Il est conseillé d'ajouter à la pause une petite variation aléatoire, afin que de nombreux clients confrontés à la même panne du fournisseur ne le frappent pas en vague synchrone au moment précis du rétablissement.

Sans classification en amont, le backoff ne sauve rien : appliqué à une cause permanente, il se contente d'étaler dans le temps des appels inutiles, dont chacun occupe un emplacement dans la limite globale du compte. Tant que la boucle martèle une clé invalide pour rien, les requêtes utiles du même compte, comme les activations réelles ou les vérifications de statut, se heurtent à la même limite et sont refusées au titre de la limitation de débit. Dans une automatisation avec des workers parallèles, décrite dans l'article sur les créations de compte via l'API, un seul processus resté bloqué dans une boucle de nouvelles tentatives peut épuiser la limite pour tous les autres.

Des journaux pour analyser un incident

Après une panne, l'analyse se fait à partir du journal, et non de la mémoire. Il faut donc en consigner assez pour répondre à la question « est-ce le fournisseur ou notre côté ? » sans reproduire le problème. Ensemble minimal : l'heure de l'appel, le point de terminaison, l'identifiant de la requête ou de l'activation, le code et le texte du refus renvoyés par le fournisseur, le numéro de la tentative et les paramètres sans les secrets : les clés et les jetons n'ont pas leur place dans le journal.

Il convient aussi de consigner non seulement la réponse du fournisseur, mais aussi la façon dont votre gestionnaire a classé la cause : temporaire, permanente ou liée à l'argent. Si le classificateur s'est trompé et qu'une cause permanente a en réalité été réessayée comme une cause temporaire, seule une telle trace le révèle, et non le seul code de réponse.

Idempotence des opérations d'argent : comment éviter un double débit

Un délai dépassé ne dit pas clairement si l'opération a été exécutée sur le serveur : la connexion a pu être coupée après le débit, mais avant que la réponse n'atteigne le client. Sans protection, le renvoi d'une telle requête ressemble pour l'API à une nouvelle opération, et conduit à un second débit pour le même achat.

La clé d'idempotence résout le problème : le client génère un identifiant unique une seule fois par opération et le transmet à chaque tentative, y compris lors des nouvelles tentatives après un délai dépassé. Le serveur mémorise le résultat fourni pour cette clé et, lors d'un nouvel appel avec la même valeur, le renvoie au lieu d'exécuter l'opération de nouveau. C'est la seule façon sûre de répéter un appel d'argent : sans clé, le risque de double débit demeure toujours.

Questions fréquentes

Faut-il réessayer une erreur 429 comme un délai dépassé ?

Oui, mais avec une pause plus longue : 429 ne signale pas une panne, mais une limite de requêtes épuisée, et une nouvelle tentative immédiate ne ferait que prolonger l'attente pour tout le monde. Reprenez la valeur de l'en-tête de la réponse si le fournisseur la fournit, ou commencez le backoff directement par une pause de plusieurs secondes plutôt que d'une seule.

Peut-on renvoyer automatiquement une requête de débit du solde après un délai dépassé ?

Pas la requête elle-même, seulement l'opération accompagnée d'une clé d'idempotence. Un délai dépassé ne dit pas si l'opération a été exécutée sur le serveur avant la coupure de la connexion ; renvoyer avec la même clé est sans danger, car le fournisseur renverra le résultat de l'opération déjà exécutée au lieu de débiter de nouveau. Sans clé, un tel renvoi risque de doubler le paiement.

Combien de tentatives prévoir raisonnablement pour une erreur temporaire ?

En règle générale, trois à cinq tentatives avec une pause exponentielle et un plafond d'attente total d'environ 30 à 60 secondes. Davantage de tentatives change rarement l'issue : si le fournisseur ne s'est pas rétabli dans cet intervalle, le problème est systémique, et il vaut mieux l'escalader que poursuivre la boucle.

Les codes par catégorie, l'en-tête de la clé d'idempotence et les paramètres de nouvelles tentatives pour chaque point de terminaison figurent dans la documentation de l'API. La réception d'événements par webhook, qui repose elle aussi sur les nouvelles tentatives et l'idempotence, est décrite dans l'article Webhooks : recevoir les codes sans polling, et les scénarios d'intégration de base dans l'article API de location de numéros.