L'extension CaptchaAI ne résout pas ? Correctifs par symptôme et type de CAPTCHA

« Solve Failed », et rien d'autre : c'est tout ce qu'affiche l'overlay de l'extension CaptchaAI quand une résolution par token échoue. Le vrai code d'erreur de l'API, lui, n'apparaît que dans les DevTools du service worker de l'extension. Quand l'extension ne résout pas, la panne se situe toujours à l'un de ces quatre niveaux : votre compte (clé API et threads du plan), les réglages de l'extension, la page elle-même (type de CAPTCHA et manière dont le site lit la réponse) ou le réseau entre votre navigateur et ocr.captchaai.com.

Ce guide vous aide à trouver le bon niveau en une minute environ, puis associe chaque message de la version actuellement publiée sur le Chrome Web Store (4.0.1, mise à jour le 7 avril 2026) à un correctif précis. Les libellés de l'extension sont cités tels quels, en anglais ; ceux de Chrome sont donnés en français quand l'interface les traduit.

Diagnostic en 60 secondes : compte, extension, page ou réseau ?

Commencez par écarter la piste du compte. Pour valider une clé, l'extension envoie elle-même une requête getbalance : le script ci-dessous voit donc exactement ce qu'elle voit, avec en prime les détails que la popup masque. Il a besoin de curl et de jq.

#!/usr/bin/env bash
# captchaai-triage.sh: is the problem the account, or the extension?
# Usage: CAPTCHAAI_API_KEY=YOUR_API_KEY ./captchaai-triage.sh
set -euo pipefail

KEY="${CAPTCHAAI_API_KEY:?Set CAPTCHAAI_API_KEY to the key from your CaptchaAI dashboard}"
API="https://ocr.captchaai.com/res.php"
command -v jq >/dev/null || { echo "This script needs jq." >&2; exit 2; }

if [ "${#KEY}" -ne 32 ]; then
  echo "Key is ${#KEY} characters; CaptchaAI keys are 32. Re-copy it without spaces." >&2
fi

# 1. Reachability and key: getbalance returns the account's total plan threads.
if ! raw=$(curl -sS --max-time 15 -F "key=${KEY}" -F "action=getbalance" -F "json=1" "$API"); then
  echo "Cannot reach ocr.captchaai.com: check DNS, VPN, firewall or corporate proxy." >&2
  exit 2
fi
echo "getbalance  -> ${raw}"
answer=$(printf '%s' "$raw" | jq -r '.request // empty' 2>/dev/null || printf '%s' "$raw")

case "$answer" in
  ERROR_WRONG_USER_KEY)     echo "Key format is wrong: it must be 32 characters."; exit 1 ;;
  ERROR_KEY_DOES_NOT_EXIST) echo "No account has this key. Copy the current key from the dashboard."; exit 1 ;;
  *IP_BANNED*)              echo "This IP is blocked after repeated bad keys. Stop the offending client, wait about 5 minutes."; exit 1 ;;
  ''|*[!0-9]*)              echo "Unexpected answer. Keep the raw response for support."; exit 1 ;;
esac

if [ "$answer" -eq 0 ]; then
  echo "Plan threads: 0. This account has no active plan, so every solve will fail."
  exit 1
fi

# 2. Saturation: threadsinfo returns total and currently working threads.
info=$(curl -sS --max-time 15 -F "key=${KEY}" -F "action=threadsinfo" "$API")
echo "threadsinfo -> ${info}"
threads=$(printf '%s' "$info" | jq -r '.threads // empty' 2>/dev/null || true)
working=$(printf '%s' "$info" | jq -r '.working_threads // empty' 2>/dev/null || true)

case "${threads}:${working}" in
  :*|*:|*[!0-9:]*) echo "Unexpected threadsinfo answer. Keep it for support."; exit 1 ;;
esac

if [ "$working" -ge "$threads" ]; then
  echo "All ${threads} threads are busy: API jobs or teammates on this key are using them."
  exit 1
else
  echo "Account OK (${working}/${threads} threads busy). Look at the extension or the page next."
fi

« Account OK » met hors de cause la facturation et la clé : cherchez du côté du navigateur, de la page ou du chemin réseau propre au navigateur.

Vérifiez d'abord que l'extension résout sur une page de test

Avant de décortiquer un site, prouvez que l'extension fonctionne. La démo reCAPTCHA de Google sert de référence : elle ne contient qu'un seul widget, que l'extension prend donc en charge sans survol. En mode Click (Grid), l'overlay affiche « Clicking Checkbox... », puis enchaîne les tours de grille ; en mode Token, il passe de « Solving reCAPTCHA V2... » à « reCAPTCHA V2 Solved! ». Pour les autres types, utilisez une page de staging configurée avec votre propre sitekey.

Le CaptchaAI Emulator n'est pas une page de test : c'est une application Windows destinée aux outils codés en dur pour l'API d'un autre fournisseur, comme le détaille la comparaison entre l'API, l'Emulator et l'extension. Si la démo fonctionne et votre site non, le problème vient de la page.

Où lire la vraie erreur : overlay, popup et service worker

L'overlay affiché sur la page

Il montre la progression (« Solving reCAPTCHA V2... », « Waiting for API result... », « Clicking grid tiles... ») et le résultat (« reCAPTCHA V2 Solved! », « Turnstile Solved! »). Un échec de résolution par token — reCAPTCHA, Turnstile, GeeTest, BLS — se résume à « Solve Failed », et un CAPTCHA image affiche « OCR Failed », sans la raison. La grille reCAPTCHA fait exception : ses messages nomment la cause (voir la section grille).

Le message « Extension reloaded. Refresh the page. » apparaît sur les CAPTCHA image dans les onglets ouverts avant une mise à jour ou un redémarrage de l'extension. Dans ces mêmes onglets, les autres types échouent ou restent muets tant que vous n'avez pas rechargé la page.

La popup

Elle indique si la clé a été validée, vos Plan Threads et les compteurs Solved, Failed et Avg Time. Plan Threads affiche la réponse brute de getbalance : si vous y lisez du texte à la place d'un nombre, ce texte est l'erreur elle-même, par exemple IP_BANNED, ou ERROR_KEY_DOES_NOT_EXIST pour une clé validée autrefois puis remplacée dans le tableau de bord. Un compteur Failed qui grimpe alors que la page n'affiche rien signifie que Show Notifications (onglet General, « Display widget overlay when solving ») est désactivé.

Le service worker

C'est lui qui émet toutes les requêtes vers l'API : les DevTools de la page ne les voient donc jamais. Pour les lire :

1. Ouvrez chrome://extensions et activez le Developer mode (« Mode développeur »).
2. Sur la carte CaptchaAI, cliquez sur service worker dans la ligne « Inspect views » (« Examiner les vues » dans un Chrome en français). Tant que cette fenêtre DevTools reste ouverte, le worker reste actif.
3. Dans l'onglet Network, filtrez sur captchaai, puis redéclenchez le CAPTCHA.
4. Ouvrez l'onglet Response de la requête in.php (l'envoi de la tâche) et de chaque requête res.php (le polling du résultat).

Quand tout va bien, in.php renvoie un ID de tâche, res.php répond quelques fois CAPCHA_NOT_READY, puis livre la réponse. En cas d'échec, c'est le code qui s'affiche, par exemple {"status":0,"request":"ERROR_ZERO_BALANCE"}. La version publiée est livrée sans journalisation de débogage et sans export de logs : l'onglet Network vous tient donc lieu de journal. Le guide de débogage des extensions de Chrome décrit aussi le bouton Errors (« Erreurs ») de la carte.

Les codes que l'extension déclenche rarement sont documentés dans la référence des codes d'erreur.

Combien de temps l'extension attend avant de déclarer un échec

Chaque type suit son propre calendrier de polling. Un « Solve Failed » qui tombe bien avant ces limites trahit en général une erreur de l'API, visible dans l'onglet Network.

Côté compte : clé refusée, IP bloquée, threads épuisés

« ✗ Invalid API key » : pourquoi la clé ne passe pas

Le bouton Validate & Save envoie la clé à res.php avec action=getbalance (un simple GET, sans json=1). Si la réponse ne commence pas par ERROR, la clé est enregistrée et « ✓ API key validated and saved! » s'affiche ; une réponse ERROR_..., ou une requête qui échoue purement et simplement, donne « ✗ Invalid API key ». Le message « ✗ Validation failed » relève d'un autre cas : la popup n'a pas pu joindre le service worker de l'extension, rechargez donc l'extension depuis chrome://extensions. Trois conséquences à connaître :

• Le réseau peut être en cause, pas la clé. Un VPN, un pare-feu ou un proxy d'entreprise qui bloque ocr.captchaai.com, ou encore un filtre DNS, produit exactement le même symptôme qu'une faute de frappe. Si le script de diagnostic n'arrive pas à se connecter, corrigez d'abord le réseau ; s'il répond « Account OK » alors que la popup refuse toujours la clé, soupçonnez un proxy ou une règle d'administration qui ne s'appliquent qu'au navigateur.
• Une clé refusée ne remplace pas l'ancienne. Tant qu'aucune nouvelle clé n'est validée, l'extension continue d'utiliser la précédente.
• Une IP bloquée peut passer pour une clé valide. La réponse documentée IP_BANNED ne commence pas par ERROR : la popup enregistre donc la clé, Plan Threads affiche IP_BANNED au lieu d'un nombre, et toutes les résolutions échouent.

Sur un poste d'entreprise, pensez au proxy filtrant géré par la DSI : demandez l'ouverture de ocr.captchaai.com plutôt que de retaper la clé.

IP_BANNED : un seul script peut bloquer tout le bureau

L'API bloque une IP après des échecs d'autorisation répétés. Dans un bureau ou un espace de coworking, toutes les machines sortent en général par la même IP publique : un seul script qui tourne encore avec une clé périmée suffit à la faire bloquer, et toutes les extensions du réseau tombent en même temps. Arrêtez d'abord ce client, puis attendez environ cinq minutes.

ERROR_ZERO_BALANCE : plus aucun thread libre

Ce code signifie qu'aucun thread n'était disponible au moment de l'envoi : soit aucun plan n'est actif (getbalance renvoie 0), soit tous les threads sont occupés (working_threads égale threads). Or l'extension n'a pas de réserve à part : elle utilise votre clé API et les mêmes endpoints in.php et res.php que votre intégration, et chaque résolution occupe un thread du plan pendant toute sa durée. Une équipe qui partage une clé partage donc un seul pool, et un job API gourmand suffit à faire échouer l'extension.

Le dimensionnement et les montées en gamme sont détaillés dans le guide des limites de threads. Pour situer les ordres de grandeur, les plus petits plans sont BASIC ($15/mois, 5 threads), STANDARD ($30/mois, 15 threads) et ADVANCE ($90/mois, 50 threads).

L'extension détecte le CAPTCHA mais ne le résout pas : six réglages à vérifier

Chacun de ces réglages suffit, à lui seul, à rendre l'extension muette. Les valeurs par défaut sont celles de la 4.0.1.

1. Extension Enabled (activé). Quand ce réglage est désactivé, la page n'est pas analysée et aucune requête n'atteint l'API. Le même silence s'installe si aucune clé n'est enregistrée ou si la page figure dans la Blacklist.
2. Les interrupteurs Auto-Solve (activés pour tous les types sauf GeeTest v4, verrouillé sur « Coming soon »). reCAPTCHA v2 en compte deux, « reCAPTCHA V2 (token) » et « reCAPTCHA V2 (grid) » ; à l'enregistrement des réglages, seul reste actif celui qui correspond au Mode reCAPTCHA choisi. Le sélecteur Token/Grid de la popup règle la même chose.
3. Handling Mode (Trigger on Hover/Focus). Il n'intervient que lorsque la page contient plusieurs CAPTCHA du même type ; un widget isolé est résolu dès sa détection, quel que soit le mode. Avec plusieurs widgets, Hover/Focus attend que vous survoliez chacun d'eux ou que vous donniez le focus à son formulaire, ce qu'un navigateur automatisé ou laissé sans surveillance ne fait jamais. Auto-Solve-All les traite tous (en Sequential par défaut ; Parallel mobilise plusieurs threads à la fois) et Manual Trigger Button attend votre clic. Si un CAPTCHA est apparu tardivement sans être détecté, faites un clic droit sur la page et choisissez CaptchaAI → Solve Captcha on this page pour relancer la détection.
4. Blacklist (désactivée). Une fois activée, une entrée sans * correspond à n'importe quelle partie de l'URL, sans tenir compte de la casse : mail bloque toutes les URL qui contiennent mail. Une entrée avec * doit couvrir l'URL entière depuis le schéma : example.com/* ne correspond jamais à https://example.com/login, alors que *example.com/* y correspond.
5. Auto Submit (désactivé pour tous les types). Le CAPTCHA est résolu, puis rien d'autre ne se passe : c'est voulu. Activez-le type par type et choisissez l'Action after solving (Submit Form, Click Button ou None) ; Click Button exige un sélecteur de bouton.
6. L'accès aux sites. Sur la page Details (« Détails ») de CaptchaAI dans chrome://extensions, réglez « Autorisez cette extension à lire et à modifier toutes vos données sur les sites Web que vous consultez » sur « Sur tous les sites », ou ajoutez le site sous « Sur des sites spécifiques » (en anglais : « On all sites », « On specific sites »). Sans cet accès, l'extension ne voit pas le CAPTCHA.

Delay (ms) et Retries (0 et 10 par type) sont volontairement absents de cette liste : le code de résolution de la 4.0.1 ne lit aucune de ces deux valeurs, donc les modifier ne provoque ni ne corrige un échec. Les limites de nouvelles tentatives de la grille sont fixes (voir la section grille).

Le guide du centre d'aide CaptchaAI emploie encore d'anciens libellés : « Enable Plugin » (aujourd'hui Extension Enabled), « Submit forms automatically » (Auto Submit) et « If error happens, repeat » (Retries). Tous les réglages sont décrits dans le guide complet de l'extension, et les options propres à chaque type dans la matrice des types pris en charge.

Conflits avec d'autres extensions : gestionnaires de mots de passe et bloqueurs

• Les gestionnaires de mots de passe comme 1Password ou Bitwarden peuvent remplir et envoyer les formulaires. Un formulaire parti avant l'arrivée de la réponse au CAPTCHA est rejeté, et l'échec ressemble à celui du CAPTCHA. L'inverse existe aussi : avec l'Auto Submit de l'extension activé, le formulaire part dès que la réponse arrive, même si le gestionnaire de mots de passe ne l'a pas encore rempli. Attendez le message de réussite et laissez un seul outil envoyer le formulaire.
• Les bloqueurs de publicité et de traçage peuvent bloquer google.com/recaptcha, recaptcha.net ou challenges.cloudflare.com : le widget ne s'affiche alors jamais. Si le snippet de console de la section Turnstile ne trouve aucun widget là où vous voyez un cadre vide, mettez le bloqueur en pause pour ce site.
• Une autre extension de résolution se dispute le même widget. N'en gardez qu'une active par profil.

Pour isoler un conflit, créez un nouveau profil Chrome avec CaptchaAI pour seule extension, ajoutez la clé et réessayez. Si tout fonctionne, réactivez vos autres extensions une par une.

Grille reCAPTCHA : « Grid solve failed » et les autres messages

Le réglage Mode de reCAPTCHA V2 détermine la méthode, et la page de réglages présélectionne Click (Grid) : l'extension coche la case, envoie les images de la grille au solveur de grilles de CaptchaAI, puis clique elle-même sur les cases correspondantes. « Waiting for tile replacements... », « Wrong answer, reloading... » et « Need more selections, re-solving... » sont des tours normaux. Chaque message d'échec, en revanche, désigne une cause distincte :

• « Grid solve failed » : la requête au solveur de grilles a échoué trois fois sur ce défi. Le code d'erreur se trouve dans l'onglet Network du service worker.
• « Grid verify failed 3 times » : CaptchaAI a répondu, mais Google a refusé trois fois la sélection cliquée. Rechargez le défi ; si cela se reproduit sur toutes les grilles d'un site, passez en mode Token.
• « Rate limited by Google » : l'écran « Try again later » de Google (« Réessayez plus tard » en français) s'affiche, signe que Google a cessé pour l'instant de servir des défis à ce navigateur ou à ce réseau. Insister aggrave la situation. Faites une pause et regardez ce qui, sur la même IP, sollicite aussi reCAPTCHA.
• « Solve runtime inactive » : la résolution a été désactivée pour la page en cours de route (Extension Enabled, la clé ou la Blacklist a changé). Rechargez la page et réessayez.
• Le mode Token. Passez reCAPTCHA v2 en Token (API) : l'extension demande alors un token à l'API (méthode userrecaptcha, à partir du sitekey et de l'URL de la page) au lieu de cliquer sur les cases, et aucun des messages de grille ne s'applique plus. Selon Google, chaque token reste valable deux minutes : soumettez le formulaire sans tarder.

Turnstile résolu, mais le token n'arrive pas dans le formulaire

L'overlay annonce « Turnstile Solved! », pourtant la vérification échoue ou le bouton d'envoi reste grisé. D'après la configuration du widget documentée par Cloudflare, Turnstile écrit son token dans un champ de formulaire caché nommé cf-turnstile-response (sauf si le site le renomme avec response-field-name ou le désactive avec response-field), et peut aussi le transmettre à un callback JavaScript. Un site qui charge Turnstile avec ?compat=recaptcha active le mode de compatibilité reCAPTCHA, qui utilise le nom de champ g-recaptcha-response ; sur ces pages, l'overlay peut afficher « Turnstile (compat) Solved! ».

Collez ce code dans la Console DevTools de la page (cadre principal) pour savoir quelle configuration vous avez, quelles familles de CAPTCHA sont présentes et si une réponse est arrivée. Il inspecte les balises script en plus des iframes, car Turnstile dessine son iframe dans un shadow root fermé, invisible pour querySelectorAll :

// Paste into the DevTools Console of the page that shows the CAPTCHA (top frame).
const report = { page: location.href, widgets: [], v3Scripts: [], families: [], answerFields: {} };

// Containers that declare a sitekey: reCAPTCHA v2 and Turnstile (hCaptcha uses .h-captcha).
// A widget rendered from JavaScript (render()) has no data-sitekey and won't be listed.
for (const el of document.querySelectorAll('[data-sitekey]')) {
  report.widgets.push({
    element: el.tagName.toLowerCase() + (el.className ? '.' + String(el.className).trim().split(/\s+/).join('.') : ''),
    sitekey: el.getAttribute('data-sitekey'),
    callback: el.getAttribute('data-callback'),
    insideForm: Boolean(el.closest('form')),
  });
}

// reCAPTCHA v3 has no widget: its sitekey is the render= value of the script URL.
for (const s of document.querySelectorAll('script[src*="/recaptcha/"]')) {
  const render = new URL(s.src).searchParams.get('render');
  if (render && render !== 'explicit') report.v3Scripts.push({ src: s.src.slice(0, 100), render });
}

// CAPTCHA families by script or frame origin. The last two are not solved by CaptchaAI.
const families = [
  ['reCAPTCHA', /^https:\/\/(www\.)?(google\.com|recaptcha\.net|gstatic\.com)\/recaptcha\//],
  ['Cloudflare Turnstile', /^https:\/\/challenges\.cloudflare\.com\//],
  ['hCaptcha (not supported)', /hcaptcha\.com/],
  ['Arkose / FunCaptcha (not supported)', /arkoselabs\.com|funcaptcha\.com/],
];
for (const el of document.querySelectorAll('script[src], iframe[src]')) {
  const match = families.find(([, pattern]) => pattern.test(el.src));
  if (!match) continue;
  const entry = { family: match[0], via: el.tagName.toLowerCase(), src: el.src.slice(0, 100) };
  if (entry.via === 'iframe') entry.visible = el.getClientRects().length > 0;
  report.families.push(entry);
}

// Where each answer must end up, and whether anything is in it yet.
for (const name of ['g-recaptcha-response', 'cf-turnstile-response']) {
  report.answerFields[name] = [...document.getElementsByName(name)].map((field) => ({
    insideForm: Boolean(field.form),
    valueLength: field.value.length,
  }));
}

console.log(JSON.stringify(report, null, 2));

Comment lire le résultat :

• cf-turnstile-response est bien dans le formulaire, mais valueLength vaut 0 après « Turnstile Solved! » : la réponse n'est jamais arrivée. Conservez la sortie et l'URL pour le support.
• Aucun champ cf-turnstile-response : soit le site règle response-field sur false et ne lit le token que via son callback (un script qui lit un champ ne voit alors rien), soit il tourne en mode de compatibilité et la réponse se trouve dans g-recaptcha-response.
• Un script Turnstile, mais une liste widgets vide : le widget est rendu en JavaScript, et le sitekey se trouve dans l'appel turnstile.render() de la page, pas dans un attribut.
• Champ rempli, formulaire non envoyé : l'Auto Submit est désactivé par défaut. La documentation de Cloudflare sur la validation côté serveur accorde aux tokens 300 secondes et une seule validation : soumettez bien avant cette limite.
• Faites correspondre le champ au widget : les réponses reCAPTCHA vont dans g-recaptcha-response, celles de Turnstile dans cf-turnstile-response ; seul le mode de compatibilité de Turnstile mélange les deux.

Et les pages « Just a moment... » ?

Les défis Cloudflare en pleine page ne sont pas des widgets Turnstile, et l'extension s'en tient volontairement à l'écart. Son manifeste exclut challenges.cloudflare.com, les chemins /cdn-cgi/challenge-platform/ et les URL contenant __cf_chl_. Lorsqu'un onglet affiche l'interstitiel « Just a moment... », l'extension le recharge une fois, puis ne l'analyse pas tant que l'interstitiel reste affiché. Il s'agit de Cloudflare Challenge, que CaptchaAI résout via l'API avec un proxy obligatoire : consultez le guide API de Cloudflare Challenge.

BLS : aucune case cliquée ou formulaire qui ne part pas

Un CAPTCHA BLS est une grille d'images 3×3 accompagnée d'un code d'instruction numérique ; l'API (méthode bls) renvoie les numéros des cases correspondantes. L'extension lit le libellé d'instruction et les images situés au premier plan (les pages BLS en superposent d'autres en dessous), envoie les images, clique sur les cases renvoyées, puis appuie sur le bouton de validation propre à la grille. Elle accorde à l'API un budget court : première vérification après 2,5 secondes, puis toutes les 2 secondes, abandon au bout de 60 secondes. Voici ce que signifie chaque issue :

• « Solving BLS... » n'apparaît jamais : la grille n'est pas encore ouverte et visible. L'option BLS Auto-Open (« Click #btnVerify to open captcha grid ») est enregistrée, mais la 4.0.1 n'en tient pas compte : ouvrez la grille vous-même.
• « Submit for new BLS captcha » : l'API n'a renvoyé aucune case correspondante, l'extension a donc validé la grille vide pour en obtenir une nouvelle, et recommence. Un ou deux de ces messages sont normaux.
• « Solve Failed » avec ERROR_BAD_PARAMETERS dans l'onglet Network : l'API a besoin des neuf images, et une grille à moitié affichée en envoie moins. Laissez la grille finir de se charger.
• « Solve Failed » avec ERROR_CAPTCHA_UNSOLVABLE : chargez une nouvelle grille.
• La grille a changé en cours de résolution : une nouvelle grille rend obsolètes les numéros de cases renvoyés. Laissez-la se charger et relancez.
• « BLS Solved! », mais le formulaire de la page ne part pas : l'envoi du formulaire après vérification relève de l'Auto Submit, désactivé par défaut ici aussi.

Les portails de rendez-vous BLS, très fréquentés par les demandeurs de visa au Maghreb et en Afrique francophone, sont des services sensibles : n'utilisez l'extension que là où vous êtes autorisé à automatiser votre propre session. Pour le format lui-même, voyez comment fonctionnent les CAPTCHA BLS.

CaptchaFox (bêta), hCaptcha et les types absents de la liste

La fiche du Chrome Web Store pour la 4.0.1 cite dix types : reCAPTCHA v2, v2 Invisible, v2 Enterprise, v3, v3 Enterprise, Cloudflare Turnstile, GeeTest v3, image, grille d'images et BLS. Pour tout le reste :

• hCaptcha et FunCaptcha (Arkose Labs) ne sont pas pris en charge par CaptchaAI, ni dans l'extension ni via l'API. Rien n'est cassé.
• GeeTest v4 est annoncé « à venir » et n'est pas encore disponible.
• CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta) fonctionnent via l'API, en bêta. Ils ne figurent pas dans la fiche du store et la 4.0.1 n'a aucun détecteur pour eux : aucun réglage de l'extension, onglets Proxy et User-Agent compris, ne les lui fera prendre en charge. CaptchaFox (bêta) exige votre propre proxy à l'envoi, ainsi que le user_agent renvoyé par l'API, à réutiliser au moment d'envoyer le token ; suivez son guide API dédié.

Onglets Proxy et User-Agent : ce qu'ils changent vraiment en 4.0.1

La page de réglages comporte un onglet Proxy (Enable Proxy, « Send proxy info with API requests », plus le type, l'hôte, le port, l'identifiant et le mot de passe) et un onglet User-Agent (une chaîne personnalisée et « Use API-Returned UA »). En 4.0.1, les requêtes de résolution ne transportent pas ces valeurs : ouvrez le Payload d'une requête in.php dans l'onglet Network du service worker, vous y trouverez la méthode, le sitekey ou les images et l'URL de la page, mais ni proxy ni proxytype. Un proxy saisi à cet endroit ne corrige donc aucun échec et n'en provoque aucun, et les codes d'erreur liés au proxy ne peuvent pas venir de l'extension.

Si un site exige que la réponse soit obtenue depuis une IP précise, passez par l'API. Ajoutez proxy (IP:PORT ou login:password@IP:PORT) et proxytype (HTTP, HTTPS, SOCKS4 ou SOCKS5) à la requête in.php. L'utilisation des proxys est désactivée par défaut sur les comptes CaptchaAI jusqu'à ce que le support l'active ; elle fonctionne pour reCAPTCHA v2 mais n'est pas prise en charge pour reCAPTCHA v3. CaptchaAI vérifie que le proxy peut ouvrir le site cible, puis charge le défi à travers lui : ERROR_BAD_PROXY signifie que le proxy est déjà marqué comme défaillant, ERROR_PROXY_CONNECTION_FAILED que le défi n'a pas pu être chargé par ce biais.

Le piège classique est le proxy protégé par une liste blanche d'IP. Ce sont les serveurs de CaptchaAI qui s'y connectent, pas votre navigateur : un proxy dont la liste blanche ne contient que l'IP de vos bureaux refusera leurs connexions. Passez à une authentification par identifiant et mot de passe, ou demandez au support quelles adresses autoriser.

CAPTCHA résolu, mais le site vous bloque quand même (diagnostic uniquement)

Le CAPTCHA n'est qu'un des éléments de la décision du site. Plutôt que d'insister, identifiez le contrôle qui échoue :

• Token expiré ou réutilisé. La documentation de vérification reCAPTCHA de Google donne à chaque token deux minutes et une seule vérification ; Turnstile accorde 300 secondes, une seule fois. Une soumission trop lente échoue avec timeout-or-duplicate. Voir le guide sur les tokens qui expirent avant la soumission.
• Le score reCAPTCHA v3. Le site applique son propre seuil. L'extension transmet son réglage Min Score (0,5 par défaut) avec la requête sous la forme min_score, mais il s'agit d'une demande, pas d'un score promis.
• Les limites de débit du site. Les réponses HTTP 429 ou les pages « too many requests » viennent du site. Ralentissez et respectez ses conditions d'utilisation.
• Une page de blocage du pare-feu. Une page HTTP 403 renvoyée par le pare-feu ou la solution anti-bot du site relève d'une décision distincte du CAPTCHA, et un token valide n'y change rien. Examinez la réponse dans l'onglet Network de la page ; le correctif se trouve du côté du propriétaire du site ou dans votre accord avec lui.

Panne pour toute l'équipe : le runbook d'incident

1. Délimitez l'incident. Tout le monde, sur tous les sites : le compte, le réseau ou une mise à jour. Tout le monde, sur un seul site : le site.
2. Vérifiez le compte, une seule fois. Une seule personne lance le script de diagnostic avec la clé partagée. ERROR_KEY_DOES_NOT_EXIST : la clé utilisée n'est plus valide et chaque navigateur doit recevoir la clé actuelle. IP_BANNED : un client configuré avec une mauvaise clé martèle l'API depuis l'IP partagée. Tous les threads occupés : un job API ou un grand nombre de collègues les monopolisent.
3. Cherchez une mise à jour. Chrome met à jour les extensions de lui-même. Comparez la version entre une machine en échec et une machine qui fonctionne, et rechargez chaque onglet resté ouvert pendant la mise à jour : l'ancienne page conserve l'ancienne copie, déconnectée, de l'extension.
4. Vérifiez le site. Si le snippet de console détecte désormais une famille que CaptchaAI ne prend pas en charge, comme hCaptcha, c'est le site qui a changé.
5. Limitez les dégâts. Désactivez l'Auto Submit pour que chacun vérifie le résultat avant l'envoi d'un formulaire, et traitez les parcours critiques à la main ou via l'API.
6. Faites remonter l'incident avec le dossier support décrit ci-dessous. La documentation de l'API ne renvoie vers aucune page de statut pour ocr.captchaai.com, l'hôte qu'appelle l'extension : lancez donc le script de diagnostic depuis deux réseaux différents, par exemple le Wi-Fi du bureau et un partage de connexion 4G. Un échec sur les deux oriente vers le service, un échec sur un seul vers ce réseau.

Le dossier à transmettre au support CaptchaAI

L'extension n'exporte aucun log : rassemblez vous-même les éléments suivants.

1. La version de l'extension (Details sur chrome://extensions) et celle de Chrome (chrome://version).
2. L'URL de la page, la sortie du snippet de console et le message exact de l'overlay.
3. La sortie du script de diagnostic.
4. Les réponses in.php et res.php relevées dans l'onglet Network du service worker, après avoir retiré la valeur key= de chaque URL : les URL de polling contiennent votre clé en clair.
5. Les réglages et les compteurs, secrets masqués, obtenus avec ce snippet dans la Console du service worker :

// Run in the CaptchaAI service-worker Console:
// chrome://extensions > Developer mode > CaptchaAI > Inspect views: service worker > Console
const stored = await chrome.storage.local.get(['captchaai_settings', 'captchaai_stats']);
const settings = structuredClone(stored.captchaai_settings ?? {}); // {} means defaults, never saved

// Never paste secrets into a ticket: mask proxy credentials, and don't read the API key at all.
if (settings.proxy) {
  for (const field of ['host', 'login', 'password']) {
    if (settings.proxy[field]) settings.proxy[field] = '[redacted]';
  }
}

console.log(JSON.stringify({
  extensionVersion: chrome.runtime.getManifest().version,
  browser: navigator.userAgent,
  settings,
  stats: stored.captchaai_stats ?? null,
}, null, 2));

Masquez aussi les données personnelles visibles dans les URL et les sorties (adresses e-mail, identifiants de session) : le support n'en a pas besoin, et c'est le réflexe de minimisation qu'attend le RGPD.

FAQ

Pourquoi l'extension résout-elle dans votre Chrome habituel, mais pas sous Playwright ou Selenium ?

Le plus souvent, le navigateur automatisé n'utilise pas le profil que vous avez configuré. La clé et les réglages sont stockés dans le chrome.storage.local de ce profil : un profil neuf ou temporaire démarre sans clé, et l'extension reste muette tant qu'aucune n'est enregistrée. Enregistrez la clé une fois dans un répertoire de données utilisateur persistant, puis réutilisez-le. Sur les pages qui contiennent plusieurs CAPTCHA d'un même type, passez aussi Handling Mode sur Auto-Solve-All, car rien ne survole les widgets dans une session automatisée. Le chargement de l'extension a également changé : depuis Chrome 137, la version officielle de Google Chrome ignore --load-extension, alors que Chromium et Chrome for Testing l'acceptent toujours. Voir comment charger l'extension dans Selenium, Puppeteer et Playwright.

Le proxy saisi dans l'extension est-il transmis à CaptchaAI ?

Non, pas en 4.0.1 : le payload des requêtes in.php ne contient ni proxy ni proxytype. Si un site exige une IP précise, passez par l'API avec ces deux paramètres, une fois l'usage des proxys activé sur votre compte par le support.

Pourquoi le compteur Failed augmente-t-il sans aucun message sur la page ?

Parce que l'overlay est désactivé. Réactivez Show Notifications dans l'onglet General (« Display widget overlay when solving ») pour revoir les messages de progression et d'échec, puis rapprochez chaque échec de son code dans l'onglet Network.