Périmètre sûr : ce guide couvre uniquement vos propres applications et environnements — QA, préproduction, production — ou des systèmes pour lesquels vous détenez une autorisation écrite. Il ne traite ni de l'automatisation de sites tiers, ni de l'évasion d'anti-bot.
Le token est valide : votre appel API direct le prouve. Si le même CAPTCHA passe en direct mais échoue depuis Selenium ou Playwright, le problème vient de la couche présentation du navigateur, pas de la résolution. Ordre de chargement des scripts, contexte iframe, en-têtes, expiration du token : la cause se cache presque toujours là. Voici comment l'isoler dans votre propre application.
Pourquoi l'API réussit là où le navigateur échoue
Un appel API direct envoie une requête propre : bons en-têtes, bonne URL, aucun script tiers. Le navigateur, lui, exécute tout le contexte de la page — widgets, callbacks, cookies de session — dont chacun peut invalider un token correct.
Comparez les deux requêtes réseau
Capturez la requête du navigateur et celle de votre appel API direct, puis confrontez-les. Les en-têtes Accept-Language, l'origine, le Referer et le cookie de session diffèrent souvent ; ces écarts expliquent la majorité des rejets. Un token émis pour une URL ne vaut que pour cette URL exacte : une redirection ou un préfixe de langue suffit à l'invalider.
Ce client Node.js minimal soumet une tâche à l'API CaptchaAI ; journalisez sa requête sortante pour la comparer à celle du navigateur :
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;
}
Inspectez le DOM et le contexte iframe
Tracez l'ordre d'apparition de l'élément CAPTCHA et la disponibilité du callback global : un décalage de quelques centaines de millisecondes entre rendu du widget et soumission suffit à produire un échec intermittent. Si le widget vit dans une iframe, le token doit être injecté dans le bon document, et l'URL transmise à l'API doit être celle de la page parente, pas celle de l'iframe.
Surveillez le timing et l'expiration du token
Un token reCAPTCHA v2 a une durée de vie courte. Tout délai entre la résolution et la soumission — polling trop espacé, attente d'un élément, débogage — rapproche l'échéance. Mesurez le temps entre l'obtention du token et son injection : s'il dépasse quelques secondes, réduisez-le d'abord, en résolvant avant la soumission.
Instrumentez et journalisez vos appels
Instrumentez vos appels CAPTCHA pour obtenir des métriques exploitables : durée d'obtention du token, code retour HTTP, identifiant de tâche, taille de la file d'attente — de quoi alimenter vos tableaux de bord et alertes de QA.
Séparez les journaux par environnement et corrélez chaque identifiant à votre traçage distribué (OpenTelemetry) : vous rejouez un scénario complet depuis un seul identifiant. Si vos workers tournent chez OVHcloud, Scaleway ou en région AWS eu-west-3 (Paris), consignez la latence réseau, qui pèse sur le budget de timing. Côté conformité, minimisez les données personnelles dans vos logs et vérifiez vos obligations RGPD avant de journaliser des requêtes complètes.
Checklist de diagnostic
- Périmètre limité à vos propres applications ou à des sources autorisées.
- Clé CaptchaAI dans un secret CI ou un coffre, jamais dans le code source.
- Durées d'appel et codes retour tracés à chaque exécution.
- Délai entre résolution et soumission mesuré et tenu sous quelques secondes.
- Retry idempotent en place pour les erreurs transitoires.
- Tests rejouables et reproductibles depuis votre intégration continue.
FAQ
Comment savoir si le token a expiré avant la soumission ?
Mesurez l'écart entre le renvoi du token par l'API et son injection. Si le CAPTCHA réapparaît alors que le token était valide à la réception, l'expiration est la cause la plus probable : réduisez le polling et soumettez sans attendre.
Quels en-têtes comparer entre l'appel API et le navigateur ?
Concentrez-vous sur Accept-Language, l'origine, le Referer et les cookies de session. Une différence sur l'un d'eux suffit à faire rejeter un token correct ; alignez la requête directe sur ce que le navigateur envoie.
Ce guide s'applique-t-il à des sites que je ne contrôle pas ?
Non. Tous les exemples portent sur vos propres applications ou des environnements de test autorisés par écrit. Pour une source externe, validez d'abord les conditions d'utilisation et la base juridique.
Comment réduire le temps de diagnostic lors d'un incident ?
Conservez des journaux corrélés par identifiant de tâche et par environnement : depuis un seul identifiant, vous rejouez toute la chaîne et localisez l'écart en quelques minutes.
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 API
- Résoudre Cloudflare Turnstile via API
Améliorez vos workflows CAPTCHA dans vos propres environnements avec une méthode reproductible. – Obtenez votre clé CaptchaAI.
