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 décrit ni l'automatisation de sites tiers, ni le contournement de protections, ni l'évasion d'anti-bot.
Le taux de résolution d'un CAPTCHA ne dépend jamais d'une seule variable : la famille visée, l'exactitude des paramètres envoyés et la latence réseau — qui, elle, change selon la région où tourne votre worker — pèsent toutes dans le résultat. Un chiffre mesuré à Paris ne se transpose donc pas tel quel à un worker déployé à Singapour ou à São Paulo. Cet article donne une méthode reproductible pour mesurer ce taux par environnement et par région avec l'API CaptchaAI, puis le garder stable en production.
Pourquoi la région déplace vos chiffres
Un worker sur OVHcloud à Gravelines ou sur Scaleway à Paris, proche de la région AWS eu-west-3, affiche un aller-retour plus court vers un service hébergé en Europe qu'un worker sur un autre continent. Cette latence s'ajoute au temps de résolution et déplace vos percentiles p95. Ne comparez donc jamais un taux de réussite brut sans préciser la région, le volume et le moment de la journée, et séparez vos mesures par environnement dès le départ.
Le workflow de résolution à instrumenter
La boucle est identique quel que soit le langage. C'est cette séquence que vous mesurez, étape par étape.
- Capturez uniquement les paramètres utiles. Inspectez la page ou l'appel réseau réel et ne récupérez que ce que la famille de CAPTCHA attend (sitekey, URL de la page, action, proxy optionnel). Stocker plus crée de fausses pistes de débogage.
- Envoyez la tâche à
https://ocr.captchaai.com/in.phpavecjson=1. Traitez tout statut différent de1comme une erreur : journalisez la réponse complète et remontez-la à votre supervision. - Interrogez le résultat sur
https://ocr.captchaai.com/res.php. Attendez 15 s avant la première interrogation, puis interrogez toutes les 5 s, avec un plafond ferme de 120 s par tâche. - Appliquez le token dans la même session que celle qui a déclenché le défi : même contexte de navigateur, même client HTTP, même jar de cookies. Une session incohérente est la première cause de rejet après résolution.
- Tracez latence, retries et acceptation en aval. La réussite du solveur et la réussite du workflow sont deux métriques distinctes ; suivez les deux.
Côté fiabilité, plafonnez les retries à trois tentatives avec backoff exponentiel et journalisez chaque échec terminal : des retries illimités masquent les vrais défauts et consomment le solde sans améliorer le taux.
Les KPI à suivre par environnement
Ce que vous ne mesurez pas, vous ne pouvez pas le défendre. Câblez ces indicateurs, découpés par région, dans le tableau de bord de votre application pour repérer les régressions avant vos utilisateurs.
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.
| KPI | Cible indicative | Ce qu'il révèle |
|---|---|---|
| Latence p50 | < 25 s (token), < 8 s (OCR image) | L'intégration est saine et n'attend pas de retries. |
| Latence p95 | < 60 s pour les CAPTCHA à token | La traîne est contenue et vos timeouts sont bien dimensionnés. |
| Taux de réussite du solveur | ≥ 95 % par famille | Vos entrées sont correctes et le solveur correspond au défi. |
| Acceptation de bout en bout | ≥ 95 % après application du token | La vérification en aval accepte le token dans la session utilisée. |
| Coût par résolution acceptée | Stable sur la semaine | Le volume n'érode pas les marges via retries ou mauvais paramètres. |
Vérifier le solde avant chaque campagne
Un ERROR_ZERO_BALANCE en pleine campagne fausse instantanément vos statistiques régionales. Ajoutez une vérification du solde en amont, côté client de 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))
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.
Observabilité et journalisation
Instrumentez chaque appel CAPTCHA pour obtenir des métriques exploitables : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente. Séparez les journaux par environnement et corrélez les identifiants à votre traçage distribué (par exemple OpenTelemetry) : vous rejouerez un scénario complet à partir d'un identifiant unique et diviserez par deux le temps de diagnostic. Si vous consignez des métriques liées à des utilisateurs finaux, minimisez les données personnelles collectées et vérifiez vos obligations RGPD avant de croiser les journaux entre régions.
Dépannage des erreurs courantes
Les erreurs ci-dessous couvrent l'essentiel des tickets pour ce type d'intégration.
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace parasite ou mauvais compte. | Recopiez la clé et stockez-la en secret CI. |
ERROR_KEY_DOES_NOT_EXIST |
Mauvaise clé de projet ou clé renouvelée. | Confirmez la clé active et régénérez le secret. |
ERROR_ZERO_BALANCE |
Solde sous le minimum par tâche. | Rechargez et ajoutez une alerte de solde. |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Entrée requise manquante ou malformée. | Revalidez URL, sitekey et champs face au HTML réel. |
ERROR_CAPTCHA_UNSOLVABLE |
Défi non résolu de façon fiable. | Réessayez une fois ; sinon, capturez le HTML et ouvrez un ticket. |
| Token refusé après résolution | Token appliqué dans une autre session que celle du défi. | Gardez résolution et soumission dans la même session. |
FAQ
Comment mesurer un taux de résolution fiable par environnement ?
Isolez chaque environnement et chaque région, puis calculez le taux de réussite et les percentiles de latence séparément sur chacun ; un chiffre agrégé masque justement les écarts régionaux qui vous intéressent. Fixez une fenêtre de mesure constante — même volume, même plage horaire — pour que deux semaines soient comparables.
Le taux de résolution varie-t-il vraiment selon la région ?
La réussite du solveur dépend surtout de la famille de CAPTCHA et de l'exactitude des paramètres. Ce qui varie nettement selon la région, c'est la latence réseau, donc vos percentiles p95 et p99 : un worker proche du service ciblé affiche une traîne plus courte qu'un worker sur un autre continent, à qualité de résolution égale.
Combien de CAPTCHA CaptchaAI peut-il traiter en parallèle ?
La capacité dépend du nombre de threads de votre offre, pas d'un quota de résolutions. L'offre BASIC ($15/mois, 5 threads) autorise cinq résolutions simultanées, avec un nombre de résolutions illimité par thread sur le mois ; les offres supérieures (STANDARD, ADVANCE, etc.) ajoutent des threads. Vous dimensionnez donc votre débit par région en fonction des threads alloués.
Guides connexes
- Démarrage rapide CaptchaAI
- QA CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Intégration CAPTCHA en intégration continue
- Résoudre reCAPTCHA v2 via l'API
Mesurez vos propres taux de résolution, région par région, avec une méthode reproductible. – Obtenez votre clé CaptchaAI.