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 sources pour lesquelles vous disposez d'une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni aucune technique visant à échapper aux protections anti-bot.
Un pipeline de cotes qui s'interrompt à 3 h du matin ne perd pas seulement une exécution : il perd la fenêtre pendant laquelle la donnée avait encore de la valeur. Quand un défi CAPTCHA apparaît sur une étape autorisée de votre collecte, la bonne réponse n'est pas de relancer le job à la main, mais de traiter la résolution comme un appel réseau parmi d'autres — avec un timeout, un retry borné et une métrique. C'est le rôle de l'API CaptchaAI ici : elle renvoie un token, votre orchestrateur poursuit sa séquence, et le reste de l'architecture ne bouge pas.
Les trois causes de panne d'une collecte de cotes
Les valeurs bougent en continu : quelques minutes d'écart suffisent à rendre un instantané inutilisable. Trois causes reviennent presque toujours.
La première est le défi qui n'apparaît qu'en production, jamais sur le poste du développeur. La deuxième, le retry non borné, qui transforme un incident de deux minutes en boucle de plusieurs heures. La troisième, l'absence de distinction entre « le CAPTCHA a été résolu » et « la requête suivante a été acceptée » : seule la seconde mesure décrit la santé réelle du pipeline.
Scénario : une équipe données à Lyon, des workers chez OVHcloud
Une équipe analytique lyonnaise surveille les cotes de son propre comparateur, déployé en préproduction, avec un relevé toutes les cinq minutes. Les workers tournent chez OVHcloud, la file d'attente est dans Redis, et deux étapes du parcours affichent un défi Cloudflare Turnstile.
Avec un plan BASIC ($15/mois, 5 threads), la file s'allonge dès que plusieurs relevés se chevauchent ; en STANDARD ($30/mois, 15 threads), les résolutions concurrentes cessent d'être le facteur limitant. La facturation est par thread, résolutions illimitées : dimensionnez le parallélisme, pas le volume mensuel. Les tarifs restent en dollars US.
Où la résolution s'insère dans le pipeline
L'orchestrateur reste maître de la séquence : il n'appelle CaptchaAI que sur les étapes où un défi est effectivement détecté. Le reste de la collecte ne change pas. Concrètement, cinq étapes suffisent :
- Ne relevez que les paramètres attendus par le type de défi (sitekey, URL de la page, action, proxy éventuel). Le superflu crée de fausses pistes de diagnostic.
- Envoyez la tâche depuis le worker qui exécute déjà le relevé, et tracez toute réponse non conforme comme une erreur.
- Interrogez le résultat à cadence fixe, avec un plafond dur par tâche : trop agressif, vous ajoutez du bruit ; trop lent, vous décalez le relevé.
- Injectez 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 cookie jar. Ailleurs, c'est la première cause de rejet après résolution.
- Mesurez séparément la réussite de la résolution et l'acceptation de la requête suivante.
Un comparateur moderne s'appuie généralement sur reCAPTCHA v2 ou v3, sur Cloudflare Turnstile ou sur des CAPTCHA image et texte : tous passent par la même API. hCaptcha et FunCaptcha ne sont pas pris en charge, et GeeTest v4 est annoncé comme à venir. Identifiez le type réellement présent sur vos pages avant de dimensionner quoi que ce soit.
Fiabilité : trois garde-fous suffisent
- Bornez les nouvelles tentatives : trois essais, backoff exponentiel, plafond à 30 secondes.
- Rendez chaque étape idempotente, pour qu'un relevé rejoué n'écrive pas deux lignes.
- Alertez dès que l'écart entre résolutions réussies et requêtes acceptées dépasse votre seuil habituel.
Exemple de code
Exemple côté client de votre propre suite de tests :
import fetch from 'node-fetch';
const API_KEY = process.env.CAPTCHAAI_KEY;
export async function createTurnstileTask(siteKey, pageUrl) {
const res = await fetch('https://api.captchaai.com/createTask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
clientKey: API_KEY,
task: {
type: 'TurnstileTaskProxyless',
websiteURL: pageUrl,
websiteKey: siteKey,
},
}),
});
const data = await res.json();
return data.taskId;
}
Observabilité et minimisation des données
Instrumentez chaque appel avec quatre valeurs : durée d'obtention du token, code retour HTTP, identifiant de tâche et profondeur de la file d'attente. Elles suffisent à distinguer une lenteur réseau d'une erreur de paramètres.
Séparez les journaux par environnement et corrélez-les à votre traçage distribué (OpenTelemetry, par exemple) : un seul identifiant rejoue alors l'incident complet. Appliquez au passage le principe de minimisation du RGPD — un relevé de cotes n'exige aucune donnée personnelle, donc ne conservez pas d'adresses IP au-delà de la durée de diagnostic.
Dépannage : les rejets les plus fréquents
Les cas ci-dessous couvrent l'essentiel des incidents observés.
| Problème | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace parasite. | Recopiez-la depuis le tableau de bord, en secret d'intégration continue. |
ERROR_ZERO_BALANCE |
Solde insuffisant pour lancer la tâche. | Rechargez le solde et ajoutez une alerte avant le seuil critique. |
ERROR_BAD_PARAMETERS |
Sitekey ou URL non conformes à la page servie. | Revalidez sur le HTML en direct, pas sur une capture ancienne. |
| Token refusé après résolution | Token injecté dans une autre session que celle du défi. | Gardez la résolution et l'envoi du formulaire dans le même contexte HTTP. |
| File d'attente qui s'allonge | Résolutions concurrentes au-delà des threads du plan. | Dimensionnez sur le parallélisme réel. |
Liste de contrôle avant mise en production
- Périmètre limité à vos propres applications ou à des sources autorisées.
- Clé API dans un coffre ou un secret d'intégration continue, jamais dans le dépôt.
- Temps de résolution et code retour tracés à chaque exécution.
- Taux de réussite et taux d'acceptation en aval suivis séparément.
FAQ
Quels types de CAPTCHA rencontre-t-on sur ce type de portail ?
Le plus souvent reCAPTCHA v2 ou v3, Cloudflare Turnstile, GeeTest v3 et des CAPTCHA image et texte, tous pris en charge par la même API. hCaptcha et FunCaptcha ne le sont pas ; GeeTest v4 est annoncé comme à venir.
Quel plan choisir pour un relevé toutes les cinq minutes ?
Cela dépend du nombre de résolutions simultanées, pas du volume mensuel. BASIC ($15/mois, 5 threads) suffit à quelques sources traitées séquentiellement ; STANDARD ($30/mois, 15 threads) ou ADVANCE ($90/mois, 50 threads) deviennent pertinents quand plusieurs collectes se chevauchent.
Pourquoi le token est-il refusé alors que la résolution a réussi ?
Presque toujours parce qu'il a été appliqué dans une autre session que celle qui a affiché le défi. Réutilisez le même contexte, cookies compris, et vérifiez que le token n'a pas expiré avant l'envoi.
Ce guide couvre-t-il des sites que je ne contrôle pas ?
Non. Les exemples portent sur vos propres applications ou sur des sources couvertes par un accord écrit. Avant toute automatisation externe, validez les conditions d'utilisation et vos obligations RGPD.
Guides connexes
- Le guide de démarrage rapide CaptchaAI
- Tester les CAPTCHA en environnement autorisé
- Valider l'endpoint API sur vos formulaires
- Intégrer la résolution CAPTCHA à votre chaîne CI
- Résoudre reCAPTCHA v2 via l'API
Passez d'un relevé fragile à une collecte instrumentée et reproductible. – Obtenez votre clé CaptchaAI.
