Circuit breaker pour vos appels CaptchaAI en 2026

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 systèmes pour lesquels vous détenez une autorisation écrite. Il ne traite ni de l'automatisation de sites tiers, ni du fait de déjouer des protections anti-bot que vous ne contrôlez pas.

Un appel de résolution CAPTCHA qui échoue en silence peut bloquer tout un pipeline. Le circuit breaker évite cela : dès que CaptchaAI renvoie trop d'erreurs d'affilée, votre code cesse d'insister, bascule sur une solution de repli et laisse le service récupérer. Ce guide décrit une configuration prête pour la production : les trois états à modéliser, la stratégie de retry, les métriques à suivre et les codes d'erreur qui déclenchent l'ouverture.

Pourquoi un circuit breaker autour des appels CaptchaAI

CaptchaAI est une dépendance HTTP externe. Sans garde-fou, un pic de latence se propage : chaque worker retente, la file d'attente gonfle, et un incident de trente secondes devient une dégradation de plusieurs minutes. Le circuit breaker coupe cette boucle en isolant le service.

Les trois états du circuit breaker

Modélisez trois états explicites plutôt qu'un simple compteur d'erreurs :

• Fermé : le trafic passe. Le breaker compte échecs et réussites sur une fenêtre glissante (par exemple les 20 dernières requêtes).
• Ouvert : le seuil d'échec est franchi (par exemple 50 %). Les appels échouent tout de suite, la solution de repli prend le relais et un minuteur démarre (30 à 60 s).
• Semi-ouvert : à l'expiration du minuteur, quelques requêtes témoins passent. Si elles réussissent, retour à l'état fermé ; sinon le circuit se rouvre.

Ne comptez que les erreurs qui traduisent une panne du service (timeouts, 5xx, réseau indisponible) : les erreurs de votre code (ERROR_WRONG_USER_KEY, ERROR_BAD_PARAMETERS) ne doivent pas ouvrir le circuit.

Architecture cible

Votre composant interne appelle CaptchaAI en HTTPS pour obtenir un token, puis l'injecte dans votre formulaire ou votre route d'API. Appliquez ce token dans la même session que celle qui a déclenché le défi CAPTCHA : même contexte de navigateur, même client HTTP, même cookie jar. Tracez chaque étape — soumission via in.php, interrogation via res.php, injection — pour repérer vite les régressions.

Configuration des secrets

La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret de votre CI, jamais dans le code source. Le déploiement la monte en variable d'environnement au runtime. Une clé expirée déclenche des ERROR_KEY_DOES_NOT_EXIST indiscernables d'une panne réelle : prévoyez sa rotation.

Stratégie de retry et de backoff

Le circuit breaker gère la panne globale ; le retry gère l'aléa unitaire. Pour chaque tâche, plafonnez à trois tentatives avec un backoff exponentiel borné (2 s, 4 s, 8 s, plafond à 30 s) et ajoutez un peu de gigue pour éviter que tous les workers ne retentent en même temps. Le retry ne vise que les erreurs transitoires ; une erreur de paramètre échoue sans retry.

Exemple de code

Exemple côté client de votre propre suite de tests, ici la vérification du solde avant de lancer un lot :

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))

Observabilité et journalisation

Quel que soit le langage, instrumentez les appels CAPTCHA : durée d'obtention du token, code retour HTTP, identifiant de tâche, taille de la file d'attente et état courant du breaker. Ces signaux alimentent vos tableaux de bord de QA et vos alertes.

Séparez les journaux par environnement et corrélez les identifiants à votre traçage distribué (OpenTelemetry, par exemple). Le passage du breaker à l'état ouvert devient alors un événement daté, recoupable avec vos autres alertes.

Mesurer la réussite : les KPIs à suivre

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 : ce sont des objectifs, pas des garanties.

Réussite du solveur et réussite du workflow sont deux métriques distinctes : suivez-les séparément et alertez sur l'écart.

Liste de contrôle avant fusion

• Le périmètre est limité à vos propres applications ou à des sources autorisées.
• La clé CaptchaAI est stockée dans un coffre ou un secret CI, jamais dans le code source.
• Les durées d'appel, les codes retour et l'état du breaker sont tracés à chaque exécution.
• Le seuil d'ouverture, le minuteur et les requêtes témoins en semi-ouvert sont configurables.
• Le retry idempotent avec backoff exponentiel borné couvre les erreurs transitoires.

Dépannage

FAQ

Quand le circuit breaker doit-il s'ouvrir ?

Quand le taux d'échec dépasse votre seuil sur une fenêtre glissante, par exemple 50 % sur les 20 dernières requêtes. Ne comptez que les erreurs de service (timeouts, 5xx, réseau) : une ERROR_BAD_PARAMETERS vient de votre code.

Faut-il distinguer la réussite du solveur de la réussite du workflow ?

Oui. Une tâche résolue n'est pas un parcours réussi : le token peut être refusé en aval s'il est injecté dans une autre session. Suivez le statut HTTP en aval à part.

Le modèle de facturation par thread change-t-il ma stratégie de retry ?

CaptchaAI facture par thread simultané, résolutions illimitées ; le plan BASIC ($15/mois, 5 threads) fixe votre parallélisme. Vos retentatives ne coûtent rien à l'unité, mais elles occupent un thread : le breaker protège cette capacité contre un retry storm.

Comment gérer une source externe dans le respect du RGPD ?

Validez d'abord les conditions d'utilisation et la base juridique. Minimisez les données personnelles collectées et journalisées, et vérifiez vos obligations RGPD avant toute automatisation.

Guides connexes

• Démarrage rapide avec CaptchaAI
• Tester vos CAPTCHA en environnement autorisé
• Tester votre endpoint d'API sur vos formulaires
• Intégrer la résolution CAPTCHA dans votre CI
• Résoudre reCAPTCHA v2 via l'API

Rendez vos workflows CAPTCHA prévisibles, incident après incident. – Obtenez votre clé CaptchaAI.