Quand l'extension CaptchaAI cesse de résoudre, la cause se résume presque toujours à quatre suspects : une clé API ou un compte invalide, un profil de navigateur ou une session corrompue, un mauvais gestionnaire de CAPTCHA, ou un token appliqué dans la mauvaise session. Passez-les en revue du plus rapide au plus subtil pour isoler la panne en minutes.
Périmètre sûr : Ce guide s'applique uniquement à vos propres applications ou à des systèmes pour lesquels vous détenez une autorisation écrite — jamais à des sites tiers ni à des protections anti-bot que vous ne contrôlez pas.
Étape 1 : vérifier la clé API et l'état du compte
Le contrôle le plus rapide et la panne la plus courante. Une clé recopiée à la main embarque souvent un espace invisible : stockez-la comme secret CI. Vérifiez ensuite que le solde n'est pas sous le minimum par tâche. Un appel de contrôle depuis votre suite de tests confirme la clé et le crédit :
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))
Si cet appel renvoie une erreur d'authentification, le problème est en amont : inutile de chercher du côté du navigateur.
Étape 2 : isoler le profil de navigateur et la session
L'extension s'exécute dans un profil de navigateur, avec ses permissions et son cache. Vérifiez qu'elle est activée pour le domaine testé, que le profil a les autorisations, et que la session ne traîne pas de cookies périmés. Recréez un profil propre : si la résolution repart, le profil précédent était en cause.
Étape 3 : sélectionner le bon gestionnaire de CAPTCHA
L'extension ne résout que si le type de la page correspond à ce qu'elle sait traiter. CaptchaAI prend en charge reCAPTCHA v2 et v3, Cloudflare Turnstile et Cloudflare Challenge, GeeTest v3, les CAPTCHA image/OCR et grille, avec CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta). En revanche, hCaptcha et FunCaptcha (Arkose Labs) ne sont pas pris en charge, et GeeTest v4 est annoncé mais pas encore disponible : dans ces cas, l'absence de résolution est attendue.
Étape 4 : injecter le token dans la bonne session
Un token valide mais rejeté à la validation signale presque toujours une session dépareillée. Appliquez le résultat dans le contexte exact qui a déclenché le défi : même navigateur, même client HTTP, même stockage de cookies. Un CAPTCHA résolu n'est pas un formulaire accepté : distinguez toujours résolution et workflow.
Tableau de dépannage des codes d'erreur
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Espace parasite ou mauvais compte. | Recopiez la clé, stockez-la en secret CI. |
ERROR_KEY_DOES_NOT_EXIST |
Clé erronée ou renouvelée. | Confirmez la clé active, régénérez le secret. |
ERROR_ZERO_BALANCE |
Solde sous le minimum par tâche. | Rechargez et posez une alerte de solde. |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Paramètre manquant ou mal formé. | Revalidez URL, sitekey et champs du type. |
ERROR_CAPTCHA_UNSOLVABLE |
Défi non résolu de façon fiable. | Réessayez une fois, sinon capturez le HTML et ouvrez un ticket. |
Mesurer et journaliser
Les seuils ci-dessous sont des objectifs d'alerte, pas des garanties : les résultats varient selon l'environnement, le volume et le moment de la journée.
- Latence de première résolution (p50, p95) et taux de réussite par famille de CAPTCHA.
- Taux d'acceptation après token, suivi séparément du taux de résolution.
- Données personnelles minimisées dans les logs, conformément à vos obligations RGPD.
Liste de contrôle avant mise en production
- La clé CaptchaAI vit dans un secret CI ou un coffre, jamais dans le code source.
- Le gestionnaire sélectionné correspond au type réellement présent sur la page.
- Le budget de retry est borné (trois tentatives, backoff exponentiel, plafond) et chaque échec est journalisé.
- Le token est injecté dans la session qui a déclenché le défi.
FAQ
Pourquoi l'extension affiche-t-elle « résolu » alors que le formulaire est refusé ?
Résolution et validation sont deux étapes distinctes : le token a bien été produit, mais appliqué dans une autre session que celle du défi. Rejouez le scénario dans le même contexte de navigateur du début à la fin.
Quel budget de retry configurer pour ne pas épuiser mon solde ?
Bornez à trois tentatives avec un backoff exponentiel plafonné (30 s). La facturation est par thread (BASIC à $15/mois, 5 threads) avec des résolutions illimitées : ce sont les tempêtes de retry, non le prix unitaire, qui font dériver votre débit.
L'extension prend-elle en charge hCaptcha ?
Non — hCaptcha n'est pas pris en charge, tout comme FunCaptcha (Arkose Labs). Concentrez-vous sur les types couverts : reCAPTCHA v2/v3, Turnstile, Cloudflare Challenge, GeeTest v3 et image.
Guides connexes
- Le démarrage rapide CaptchaAI
- La QA CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Intégrer la résolution CAPTCHA en CI
- Résoudre reCAPTCHA v2 via l'API
Fiabilisez vos workflows CAPTCHA avec une approche méthodique et reproductible. – Obtenez votre clé CaptchaAI.
