Périmètre sûr : Ce guide s'applique exclusivement à vos propres applications et à vos environnements de QA, de préproduction ou de production, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne concerne ni l'automatisation de sites tiers, ni la neutralisation de protections anti-bot.
Quand l'extension CaptchaAI refuse de valider ou d'enregistrer votre clé API, la cause tient presque toujours à l'une de ces trois situations : un espace parasite copié avec la clé, une clé rattachée au mauvais compte, ou un solde tombé à zéro qui bloque la première tâche. Ce ne sont pas des bugs de l'extension, mais des erreurs d'état de compte et de saisie, faciles à isoler. Ce guide vous montre comment reproduire le problème par l'API, lire le bon code d'erreur et corriger chaque cas sans quitter votre éditeur.
Vérifier la clé et le solde par l'API
Le moyen le plus rapide de savoir si une clé est bonne consiste à l'interroger hors de l'extension. Un appel à getBalance confirme d'un coup que la clé existe, qu'elle est rattachée au bon compte et que le solde est suffisant. Isolez ce test dans votre propre suite plutôt que de déboguer à l'aveugle dans le navigateur :
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))
Un solde renvoyé signifie que la clé est valide ; une exception HTTP vous donne directement le code d'erreur à traiter. Si cet appel réussit alors que l'extension échoue, le problème vient du navigateur : testez la clé dans un profil neuf, sans autre extension. Stockez toujours la clé dans un secret CI ou un coffre, jamais en clair dans le code.
Tracer les appels pour diagnostiquer plus vite
Instrumentez chaque appel CAPTCHA pour obtenir des signaux exploitables : durée totale d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente interne. Ces métriques alimentent vos tableaux de bord de QA et déclenchent vos alertes.
Séparez les journaux par environnement et corrélez chaque identifiant à votre traçage distribué, par exemple via OpenTelemetry. Vous rejouez ainsi un scénario complet depuis un seul identifiant et divisez par deux le temps de diagnostic.
Codes d'erreur à connaître
Ce tableau couvre l'essentiel des tickets de validation de clé ; chaque ligne est un correctif applicable immédiatement.
| Code d'erreur | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace parasite ou mauvais compte. | Recopiez la clé depuis le tableau de bord et enregistrez-la comme secret CI. |
ERROR_KEY_DOES_NOT_EXIST |
Clé d'un ancien projet ou régénérée après rotation. | Confirmez la clé active dans le tableau de bord et remplacez le secret. |
ERROR_ZERO_BALANCE |
Solde inférieur au minimum par tâche. | Rechargez le compte et ajoutez une alerte de solde. |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Paramètre requis absent ou mal formé. | Revalidez l'URL de page et le sitekey face au HTML réel. |
| Token refusé après résolution | Token appliqué dans une autre session que celle du défi. | Gardez la résolution et l'envoi du formulaire dans la même session. |
Liste de contrôle avant la mise en production
- Le périmètre est strictement limité à vos propres applications ou à des sources autorisées.
- La clé CaptchaAI est stockée dans un secret CI ou un coffre, jamais dans le code source.
- Les durées d'appel et les codes retour sont tracés à chaque exécution.
- Une stratégie de retry idempotent (trois tentatives, backoff exponentiel) gère les erreurs transitoires.
- Vos tests sont rejouables et reproductibles depuis votre intégration continue.
FAQ
Pourquoi ma clé API est-elle refusée par l'extension CaptchaAI ?
Dans la quasi-totalité des cas, la clé contient un espace copié par erreur, appartient à un autre compte, ou le solde est à zéro. Recopiez-la proprement, vérifiez le compte actif et le solde, puis retestez : la validation aboutit presque toujours à ce stade.
Où trouver ma clé API pour la copier sans erreur ?
Votre clé se trouve dans le tableau de bord CaptchaAI, dans la section dédiée à l'API. Copiez-la depuis le champ prévu à cet effet plutôt que depuis un e-mail ou une capture d'écran, et collez-la sans espace avant ou après.
L'extension fonctionne-t-elle si mon solde est à zéro ?
Non. Chaque plan CaptchaAI est facturé au thread — BASIC ($15/mois, 5 threads) au minimum — et un solde nul renvoie ERROR_ZERO_BALANCE dès la première résolution. Rechargez le compte, puis ajoutez une alerte de solde.
L'extension prend-elle en charge hCaptcha ?
Non — pas encore pris en charge. L'extension CaptchaAI résout reCAPTCHA v2 et v3, Cloudflare Turnstile et Cloudflare Challenge, GeeTest v3, ainsi que les CAPTCHA image/OCR et en grille d'images.
Guides connexes
- Démarrage rapide CaptchaAI
- QA CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Intégration CAPTCHA en CI
- Résoudre reCAPTCHA v2 via l'API
Validez votre clé une bonne fois et fiabilisez vos workflows CAPTCHA. – Obtenez votre clé CaptchaAI.
