Concevoir un budget de retry pour les appels CaptchaAI

Périmètre sûr : ce guide s'applique uniquement à vos propres applications et à vos environnements de QA, de préproduction ou de production, ou à des sources pour lesquelles vous disposez d'une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni la gestion de protections que vous ne contrôlez pas.

Un budget de retry, c'est le nombre maximal de nouvelles tentatives qu'un appel à l'API CaptchaAI a le droit de consommer avant d'abandonner proprement. La bonne valeur par défaut tient en trois règles : trois tentatives, un backoff exponentiel borné et un plafond de temps par tâche. Au-delà, vous ne corrigez plus une erreur transitoire, vous masquez un vrai défaut et vous consommez du solde pour rien.

La suite détaille trois décisions : quelles erreurs réessayer, à quelle cadence interroger le résultat, et quelles métriques trahissent un budget mal calibré.

Le déroulé en bref

1. Soumettez la tâche et conservez son identifiant.
2. Patientez 15 s, puis interrogez le résultat toutes les 5 s, avec un plafond de 120 s.
3. Sur échec transitoire, réessayez en backoff exponentiel borné : trois tentatives, plafond à 30 s.
4. Appliquez le token dans la session d'origine et journalisez chaque échec terminal.

Distinguer erreurs transitoires et permanentes

Toutes les erreurs ne méritent pas un retry. Un réseau coupé, un timeout ou un ERROR_CAPTCHA_UNSOLVABLE isolé sont transitoires : une nouvelle tentative aboutit souvent. Mais ERROR_WRONG_USER_KEY, ERROR_ZERO_BALANCE ou des paramètres invalides sont permanents et échouent immédiatement. Journalisez chaque échec terminal avec son identifiant de tâche.

Séparer la cadence de polling du backoff

Deux temporisations cohabitent ; les confondre déclenche des avalanches de requêtes.

• La cadence de polling rythme l'attente d'un même résultat : patientez 15 s avant la première interrogation, puis interrogez toutes les 5 s, avec un plafond de 120 s par tâche.
• Le backoff des retries espace deux tentatives complètes après un échec transitoire : doublez le délai à chaque essai (2 s, 4 s, 8 s) avec un plafond à 30 s.

Rendre chaque tentative idempotente

Un budget de retry n'est sûr que si chaque tentative est idempotente : rejouer un appel ne doit jamais produire deux effets. Tant qu'une résolution est en cours, interrogez le même identifiant de tâche au lieu d'en soumettre une nouvelle à chaque essai, et appliquez toujours le token dans la session qui a déclenché le défi. Sans cette discipline, un simple retry double la consommation de threads et peut valider deux fois le même formulaire.

Vérifier le solde avant une rafale

Contrôlez le solde avant une file de tâches : une rafale entière peut échouer sur ERROR_ZERO_BALANCE qu'une simple alerte aurait évité.

import os
import requests

API_KEY = os.environ['CAPTCHAAI_KEY']

def get_balance() -> float:
    resp = requests.post(
        'https://api.captchaai.com/getBalance',
        json={'clientKey': API_KEY},
        timeout=15,
    )
    resp.raise_for_status()
    return float(resp.json().get('balance', 0))

Mesurer si le budget est bien calibré

Un budget ne se règle pas au jugé, il se mesure. Câblez ces objectifs dans vos tableaux de bord.

Les chiffres ci-dessous reposent sur des mesures observées et des retours d'utilisateurs. Les résultats varient selon l'environnement, le volume et le moment de la journée.

Un worker sur OVHcloud ou en région eu-west-3 (Paris) voit sa p95 grimper si le plafond de polling est trop bas.

Liste de contrôle

• Le périmètre reste limité à vos applications ou à des sources autorisées.
• La clé CaptchaAI vit dans un coffre ou un secret CI, jamais dans le code.
• Seules les erreurs transitoires déclenchent une nouvelle tentative.
• Le budget est plafonné à trois tentatives avec backoff borné.
• Chaque échec terminal est journalisé avec son identifiant de tâche.

Dépannage

FAQ

Combien de tentatives faut-il autoriser par appel ?

Trois au maximum, avec un backoff exponentiel borné. Si trois tentatives ne suffisent pas, le problème est ailleurs : paramètres, réseau ou quota.

Faut-il réessayer toutes les erreurs de l'API ?

Non. Réessayez uniquement les erreurs transitoires : réseau, timeout, ERROR_CAPTCHA_UNSOLVABLE isolé. Les erreurs de clé, de solde ou de paramètres sont permanentes et doivent échouer immédiatement.

Le budget de retry augmente-t-il le coût ?

Indirectement. La facturation CaptchaAI repose sur les threads, pas sur les tentatives, mais les boucles de retry mobilisent des threads plus longtemps. Un budget borné protège votre débit autant que votre solde.

Où stocker la clé CaptchaAI ?

Dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou un secret de CI, monté en variable d'environnement au runtime. Jamais en dur dans le dépôt : une clé versionnée finit tôt ou tard dans un log ou un fork.

Guides connexes

• Démarrage rapide CaptchaAI
• QA CAPTCHA en environnements autorisés
• Tester l'endpoint API sur vos formulaires
• Intégration CAPTCHA en continu
• Résoudre reCAPTCHA v2 via l'API

Un budget de retry mesurable transforme les incidents CAPTCHA en signaux exploitables. – Obtenez votre clé CaptchaAI.