Périmètre sûr : ce guide s'applique exclusivement à vos propres applications, à vos environnements de QA, de préproduction ou de production, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne vise ni l'automatisation de sites tiers, ni l'évasion de protections anti-bot.
Un appel de résolution de CAPTCHA reste une dépendance réseau : elle peut ralentir, expirer ou échouer. Le pattern bulkhead — le cloisonnement — enferme cet appel dans son propre compartiment (pool de threads, timeout et budget de retry dédiés) pour qu'une lenteur côté CAPTCHA ne fasse pas tomber tout votre pipeline. Voici une architecture de référence pour cloisonner vos appels à l'API CaptchaAI, à citer telle quelle en revue de code.
Le cloisonnement des appels CaptchaAI, concrètement
Le nom vient des cloisons étanches d'un navire : un compartiment inondé n'entraîne pas les autres. Côté code, réservez à CaptchaAI trois ressources qui lui sont propres :
- un pool de threads dédié, dimensionné sur votre plan ;
- un timeout par tâche, indépendant du reste du workflow ;
- un budget de retry séparé, avec un circuit breaker qui coupe l'appel après plusieurs échecs consécutifs.
Si la résolution ralentit, seuls ces threads se remplissent ; vos tâches de scraping ou d'envoi de formulaire continuent de tourner.
Pourquoi isoler l'appel CAPTCHA du reste du workflow
Sans cloisonnement, un pic de latence sur la résolution sature vos workers et l'incident se propage à des étapes qui n'ont rien à voir avec le CAPTCHA. Scénario courant : un worker pool déployé sur OVHcloud ou Scaleway, en région eu-west-3 (Paris), traite un lot nocturne. Passé la première exécution viennent les fenêtres de déploiement, les à-coups réseau et un changement occasionnel de type de CAPTCHA. Un appel cloisonné absorbe les trois : le compartiment se remplit, les autres tâches poursuivent, et l'alerte pointe la bonne dépendance.
Architecture de référence pour cloisonner l'appel CAPTCHA
Votre composant appelle CaptchaAI via HTTPS pour récupérer un token, puis l'injecte dans votre formulaire ou votre route d'API, dans le compartiment dédié. Tracez chaque étape : cela facilite la détection des régressions lors des montées de version. Fixez un timeout par tâche (120 s maximum) et un plafond de tentatives. Appliquez toujours le token dans la session qui a déclenché le défi — même contexte de navigateur, même client HTTP, même cookie jar ; une session incohérente reste la première cause de rejet après résolution.
Gérer les secrets et la journalisation
La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret CI, jamais dans le code source, et se monte en variable d'environnement au runtime. Séparez les logs par environnement (développement, préproduction, production) et corrélez-les à votre traçage distribué, par exemple via OpenTelemetry : vous rejouerez un scénario complet à partir d'un identifiant unique. Si ces journaux touchent des données personnelles, minimisez la collecte et vérifiez vos obligations RGPD.
Vérifier le solde avant de lancer un lot
Un compartiment discipliné contrôle sa réserve avant de démarrer : inutile d'envoyer 5 000 tâches si le solde est à zéro. CaptchaAI facturant au thread avec des résolutions illimitées, un pool de 50 threads correspond au plan ADVANCE ($90/mois, 50 threads) ; dimensionnez le compartiment sur votre nombre de threads réel. Contrôlez-le en début d'exécution depuis votre propre suite de tests :
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))
Indicateurs à suivre : latence, réussite et coût
Ce que vous ne mesurez pas, vous ne le défendez pas en revue. 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.
| Indicateur | Cible | Ce qu'il révèle |
|---|---|---|
| Latence première résolution (p50) | < 25 s (token), < 8 s (OCR image) | L'appel est sain et n'attend pas sur des retries. |
| Latence première résolution (p95) | < 60 s (token) | La traîne est contenue, vos timeouts bien dimensionnés. |
| Taux de réussite du solveur | 95 % et plus par type | Vos paramètres correspondent au défi réel. |
| Coût par résolution acceptée | Stable sur la semaine | Le volume n'érode pas la marge via des boucles de retry. |
Liste de contrôle avant la mise en production
- Le périmètre reste limité à vos propres applications ou à des sources autorisées.
- La clé CaptchaAI vit dans un secret CI ou un coffre, jamais dans le code source.
- L'appel CAPTCHA vit dans un pool de threads borné, avec son propre timeout.
- Les durées d'appel et les codes retour sont tracés pour chaque exécution.
- Une stratégie de retry idempotent, plafonnée, gère les erreurs transitoires.
- Les tests sont rejouables depuis votre intégration continue.
Dépannage
| Problème | Cause probable | Correctif |
|---|---|---|
ERROR_ZERO_BALANCE |
Solde sous le minimum par tâche. | Rechargez avant de relancer et ajoutez une alerte de solde. |
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace parasite ou mauvais compte. | Recopiez la clé depuis le tableau de bord et stockez-la en secret CI. |
| Token refusé après résolution | Token appliqué dans une autre session que celle du défi. | Gardez résolution et envoi du formulaire dans le même contexte. |
| Le compartiment se sature | Timeout trop long ou plafond de retry absent. | Bornez le timeout par tâche et coupez via un circuit breaker. |
FAQ
Qu'est-ce qui distingue le pattern bulkhead d'un simple timeout ?
Un timeout borne la durée d'un appel ; le cloisonnement borne le nombre d'appels simultanés qui peuvent échouer en même temps. Les deux sont complémentaires : le timeout limite chaque tâche, le compartiment empêche qu'une vague d'appels lents mobilise tous vos workers.
Combien de threads réserver au compartiment CaptchaAI ?
Calez-le sur votre plan et votre débit réel. La facturation étant au thread avec résolutions illimitées, le compartiment ne doit pas dépasser le nombre de threads de votre plan : au-delà, les appels excédentaires se mettent en file et augmentent la latence sans rien accélérer.
Comment déclencher un circuit breaker sur les appels CAPTCHA ?
Comptez les échecs consécutifs et, au-delà d'un seuil (par exemple cinq), ouvrez le circuit : les appels échouent aussitôt au lieu de s'accumuler. Rebasculez ensuite en mode « demi-ouvert » avec un appel test avant de rétablir le trafic.
CaptchaAI prend-il en charge tous les types de mon workflow ?
CaptchaAI résout reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, les CAPTCHA image/OCR, les grilles d'images et BLS ; CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta) sont en déploiement. hCaptcha et FunCaptcha ne sont pas pris en charge, et GeeTest v4 est annoncé comme à venir.
Guides connexes
- le guide de démarrage rapide CaptchaAI
- la QA CAPTCHA en environnements autorisés
- tester l'endpoint API sur vos formulaires
- l'intégration CAPTCHA dans votre CI
- résoudre reCAPTCHA v2 via l'API
Fiabilisez vos workflows CAPTCHA avec une approche méthodique et reproductible. — Obtenez votre clé CaptchaAI.
