Erreurs et correctifs courants de résolution de reCAPTCHA v2

La plupart des échecs de reCAPTCHA v2 se répartissent en trois catégories : erreurs au stade de la demande (mauvais paramètres envoyés à l'API), problèmes au stade du résultat (problèmes d'interrogation ou tâches insolubles) et rejets de la page cible (l'API renvoie un jeton valide mais la page l'ignore). Les plus grands coupables sont presque toujours les mêmes : un googlekey incorrect, un pageurl incorrect, une exécution de rappel manquante ou des jetons expirés.

Ce guide passe en revue tous les modèles de défaillance courants avec la solution exacte pour chacun. Si vous débutez dans la résolution de reCAPTCHA v2, lisezComment résoudre reCAPTCHA v2 à l'aide de l'APId'abord.

Les quatre plus gros points d'échec de reCAPTCHA v2

Avant d'examiner les codes d'erreur individuels, vérifiez-les d'abord : ils couvrent 80 % des échecs.

1. googlekey erroné ou manquant

Le googlekey (sitekey) provient de l'attribut data-sitekey du widget reCAPTCHA ou du paramètre k dans l'URL d'ancrage. Si cette valeur est erronée, vide ou copiée à partir d'une autre page, l'API rejette immédiatement la tâche avec ERROR_GOOGLEKEY ou ERROR_WRONG_GOOGLEKEY.

Comment trouver la bonne clé de site :

# Look for data-sitekey in the page HTML
# <div class="g-recaptcha" data-sitekey="6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-"></div>

# Or find it in the anchor URL
# https://www.google.com/recaptcha/api2/anchor?k=6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-

2. Mauvais pageurl

Le pageurl doit être l'URL exacte où le widget reCAPTCHA se charge. Si le widget se trouve dans une iframe hébergée sur un domaine différent, vous avez besoin de l'URL de l'iframe, et non de l'URL de la page parent. L'envoi d'une mauvaise URL provoque ERROR_PAGEURL ou ERROR_BAD_TOKEN_OR_PAGEURL.

3. Rappel non exécuté

Certaines pages utilisent une fonction de rappel JavaScript au lieu du champ masqué g-recaptcha-response. Si vous injectez le jeton dans le champ masqué mais que la page attend un rappel, le formulaire n'est jamais soumis. Recherchez data-callback sur le widget ou une propriété callback dans grecaptcha.render().

4. Jeton expiré ou réutilisé

Les jetons reCAPTCHA sont valables pour une seule utilisation et expirent après environ 2 minutes. Si votre automatisation prend trop de temps entre la réception du token et la soumission du formulaire, ou si elle réutilise un token, la page cible le rejette en silence.

Erreurs au stade de la requête (in.php)

Ces erreurs se produisent lorsque vous soumettez la tâche CAPTCHA à https://ocr.captchaai.com/in.php.

Exemple : Corriger la demande avec gestion des erreurs

import requests

def submit_recaptcha_v2(api_key, sitekey, page_url):
    response = requests.get("https://ocr.captchaai.com/in.php", params={
        "key": api_key,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": page_url,
        "json": 1
    })

    data = response.json()

    if data.get("status") == 1:
        return data["request"]  # task ID

    error = data.get("request", "UNKNOWN_ERROR")

    if error == "ERROR_WRONG_USER_KEY":
        raise ValueError("API key format is invalid. Must be 32 characters.")
    elif error == "ERROR_ZERO_BALANCE":
        raise RuntimeError("Account balance is zero. Top up at captchaai.com")
    elif error == "ERROR_PAGEURL":
        raise ValueError("pageurl parameter is missing from request")
    elif error in ("ERROR_GOOGLEKEY", "ERROR_WRONG_GOOGLEKEY"):
        raise ValueError(f"Invalid sitekey. Verify the data-sitekey value on the page.")
    elif error == "ERROR_BAD_TOKEN_OR_PAGEURL":
        raise ValueError("Sitekey/pageurl mismatch. Check if widget is in an iframe.")
    else:
        raise RuntimeError(f"API error: {error}")

# Usage
task_id = submit_recaptcha_v2("YOUR_API_KEY", "6Le-wvkSAAAAAN...", "https://example.com/login")
print(f"Task submitted: {task_id}")

async function submitRecaptchaV2(apiKey, sitekey, pageUrl) {
  const params = new URLSearchParams({
    key: apiKey,
    method: "userrecaptcha",
    googlekey: sitekey,
    pageurl: pageUrl,
    json: 1,
  });

  const res = await fetch(`https://ocr.captchaai.com/in.php?${params}`);
  const data = await res.json();

  if (data.status === 1) return data.request;

  const error = data.request || "UNKNOWN_ERROR";
  const fixes = {
    ERROR_WRONG_USER_KEY: "API key format is invalid. Must be 32 characters.",
    ERROR_ZERO_BALANCE: "Account balance is zero. Top up at captchaai.com",
    ERROR_PAGEURL: "pageurl parameter is missing from request",
    ERROR_GOOGLEKEY: "Invalid sitekey. Check the data-sitekey attribute.",
    ERROR_BAD_TOKEN_OR_PAGEURL: "Sitekey/pageurl mismatch. Check iframe context.",
  };

  throw new Error(fixes[error] || `API error: ${error}`);
}

// Usage
const taskId = await submitRecaptchaV2("YOUR_API_KEY", "6Le-wvkSAAAAAN...", "https://example.com/login");
console.log(`Task submitted: ${taskId}`);

Erreurs de l'étape de résultat (res.php)

Ces erreurs se produisent lors de l'interrogation du résultat de https://ocr.captchaai.com/res.php.

Exemple : interrogation avec gestion appropriée des erreurs

import time
import requests

def poll_result(api_key, task_id, timeout=120):
    start = time.time()

    while time.time() - start < timeout:
        time.sleep(5)

        response = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": api_key,
            "action": "get",
            "id": task_id,
            "json": 1
        })

        data = response.json()

        if data.get("status") == 1:
            return data["request"]  # solved token

        error = data.get("request", "")

        if error == "CAPCHA_NOT_READY":
            continue  # normal — keep waiting
        elif error == "ERROR_CAPTCHA_UNSOLVABLE":
            raise RuntimeError("CAPTCHA unsolvable. Submit a new task with fresh params.")
        elif error in ("ERROR_WRONG_ID_FORMAT", "ERROR_WRONG_CAPTCHA_ID"):
            raise ValueError(f"Invalid task ID: {task_id}")
        else:
            raise RuntimeError(f"Polling error: {error}")

    raise TimeoutError(f"Solve timed out after {timeout}s")

# Usage
token = poll_result("YOUR_API_KEY", task_id)
print(f"Token: {token[:50]}...")

async function pollResult(apiKey, taskId, timeout = 120000) {
  const start = Date.now();

  while (Date.now() - start < timeout) {
    await new Promise((r) => setTimeout(r, 5000));

    const params = new URLSearchParams({
      key: apiKey,
      action: "get",
      id: taskId,
      json: 1,
    });

    const res = await fetch(`https://ocr.captchaai.com/res.php?${params}`);
    const data = await res.json();

    if (data.status === 1) return data.request;

    if (data.request === "CAPCHA_NOT_READY") continue;
    if (data.request === "ERROR_CAPTCHA_UNSOLVABLE")
      throw new Error("Unsolvable. Submit a new task.");
    throw new Error(`Polling error: ${data.request}`);
  }

  throw new Error(`Solve timed out after ${timeout / 1000}s`);
}

Rejets de la page cible

L'API a renvoyé un jeton valide mais le site cible le rejette toujours. Ce sont les échecs les plus difficiles à déboguer car l’API pense que tout a fonctionné.

Jeton injecté dans le mauvais champ

Certaines pages recherchent le jeton dans la zone de texte g-recaptcha-response. D'autres utilisent grecaptcha.getResponse(). D'autres s'attendent à un rappel. Si vous choisissez la mauvaise méthode d’injection, la soumission du formulaire échoue silencieusement.

Correction : Inspectez la page pour déterminer le chemin attendu :

# Method 1: Hidden field injection
driver.execute_script(
    'document.getElementById("g-recaptcha-response").innerHTML = arguments[0];',
    token
)

# Method 2: Callback execution (check data-callback attribute)
driver.execute_script(f'onCaptchaSuccess("{token}");')

# Method 3: Direct form field + submit
driver.execute_script(
    'document.querySelector("[name=g-recaptcha-response]").value = arguments[0];',
    token
)
driver.find_element("css selector", "form").submit()

Rappel non déclenché

Si le widget a data-callback="onSuccess" ou utilise grecaptcha.render() avec une propriété callback, le fait de remplir seul le champ masqué ne fait rien. Vous devez appeler la fonction de rappel directement.

Correction : Recherchez et rappelez le rappel :

// In browser console or Puppeteer/Playwright
// Check for data-callback
const widget = document.querySelector('.g-recaptcha');
const callbackName = widget?.getAttribute('data-callback');
if (callbackName && window[callbackName]) {
  window[callbackName](token);
}

Jeton expiré

Si plus d'environ 2 minutes s'écoulent entre la réception du jeton et l'envoi du formulaire, Google le rejette. Ceci est courant dans les pipelines d’automatisation lents.

Correction : Envoyez le formulaire immédiatement après avoir reçu le jeton. Si votre pipeline est lent, demandez la résolution plus près de l'étape de soumission plutôt qu'au début.

Le widget est dans une iframe

Si le reCAPTCHA se charge dans une iframe provenant d'un domaine différent, vous devez utiliser l'URL source de l'iframe sous la forme pageurl, et non l'URL de la page parent. L'erreur ERROR_BAD_TOKEN_OR_PAGEURL signale généralement ce problème.

Correction : Inspectez la page, recherchez l'iframe contenant le reCAPTCHA et utilisez l'URL src de cette iframe comme pageurl.

Liste de contrôle de diagnostic rapide

FAQ

Pourquoi reCAPTCHA v2 échoue-t-il même lorsque la requête semble correcte ?

Les trois causes les plus courantes sont : (1) le pageurl ne correspond pas au contexte réel du widget, en particulier lorsque le widget se trouve dans une iframe, (2) la page attend une fonction de rappel mais vous n'avez rempli que le champ masqué, ou (3) le jeton a expiré avant d'envoyer le formulaire.

Quelle est l’erreur de résolution de reCAPTCHA v2 la plus courante ?

Utiliser le mauvais googlekey ou le mauvais pageurl. Ceci est particulièrement courant lorsque le widget reCAPTCHA se charge dans une iframe sur un domaine ou sous-domaine différent : la clé du site et l'URL doivent correspondre au contexte iframe, et non à la page parent.

Que signifie CAPCHA_NOT_READY ?

Cela signifie que le CAPTCHA est toujours en cours de résolution. Ce n'est pas une erreur. Attendez 5 secondes et interrogez à nouveau res.php. Les temps de résolution typiques de reCAPTCHA v2 sont de 15 à 60 secondes.

Que dois-je faire si l'API renvoie un jeton mais que la page le rejette toujours ?

Vérifiez trois choses dans l'ordre : (1) La page utilise-t-elle un rappel ? Recherchez data-callback sur le widget. (2) Votre pageurl est-il correct, surtout si le widget est dans une iframe ? (3) Est-ce que plus de 2 minutes se sont écoulées entre la réception et l'utilisation du jeton ?

Comment gérer ERROR_CAPTCHA_UNSOLVABLE ?

Soumettez une nouvelle tâche avec de nouveaux paramètres. Ne réessayez pas avec le même ID de tâche. Si cette erreur se produit à plusieurs reprises, vérifiez que votre clé de site et votre URL de page correspondent à la page réelle et que le type CAPTCHA est standard reCAPTCHA v2 (et non Enterprise – qui nécessite des paramètres différents).

Corrigez votre flux de travail reCAPTCHA v2

1. Vérifiez vos entrées — extrayez googlekey de data-sitekey et utilisez l'URL exacte de la page (vérifiez les iframes)
2. Vérifiez la méthode d'injection : déterminez si la page attend un champ caché, un rappel ou les deux.
3. Soumettre immédiatement — utilisez le jeton dans les 2 minutes suivant sa réception
4. Ajouter la gestion des erreurs — utilisez les exemples de code ci-dessus pour détecter et gérer chaque type d'erreur

Commencez à résoudre reCAPTCHA v2 avec leSolveur CaptchaAI. Obtenez votre clé API auprès decaptchaai.com/api.php.

Guides associés

• Comment résoudre reCAPTCHA v2 à l'aide de l'API- tutoriel complet étape par étape
• Comment résoudre le rappel reCAPTCHA v2 à l'aide de l'API— guide spécifique au rappel
• Le défi de la grille reCAPTCHA expliqué– comment fonctionnent les défis de grille
• Référence des codes d'erreur CaptchaAI- liste complète des codes d'erreur