Errores comunes al resolver reCAPTCHA v2 y cómo solucionarlos

La mayoría de las fallas de reCAPTCHA v2 se dividen en tres grupos: errores en la etapa de solicitud (parámetros incorrectos enviados a la API), problemas en la etapa de resultados (problemas de sondeo o tareas sin solución) y rechazos de la página de destino (la API devuelve un token válido pero la página lo ignora). Los mayores culpables son casi siempre los mismos: googlekey incorrecto, pageurl incorrecto, omitir la función callback o tokens caducados.

Esta guía analiza cada patrón de falla común con la solución exacta para cada uno. Si eres nuevo resolviendo reCAPTCHA v2, lee Cómo resolver reCAPTCHA v2 usando la API primero.

Los cuatro mayores puntos de falla de reCAPTCHA v2

Antes de profundizar en los códigos de error individuales, verifíquelos primero: cubren el 80% de las fallas.

1. googlekey incorrecto o faltante

El googlekey (clave del sitio) proviene del atributo data-sitekey en el widget reCAPTCHA o del parámetro k en la URL de anclaje. Si este valor es incorrecto, está en blanco o se copia de una página diferente, la API rechaza la tarea inmediatamente con ERROR_GOOGLEKEY o ERROR_WRONG_GOOGLEKEY.

Cómo encontrar la clave de sitio correcta:

# 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. pageurl incorrecto

pageurl debe ser la URL exacta donde se carga el widget reCAPTCHA. Si el widget está dentro de un iframe alojado en un dominio diferente, necesitará la URL del iframe, no la URL de la página principal. Enviar la URL incorrecta provoca ERROR_PAGEURL o ERROR_BAD_TOKEN_OR_PAGEURL.

3. Callback no ejecutado

Algunas páginas utilizan una función callback de JavaScript en lugar del campo oculto g-recaptcha-response. Si inyectas el token en el campo oculto pero la página espera un callback, el formulario nunca se envía. Busca data-callback en el widget o una propiedad callback en grecaptcha.render().

4. Token caducado o reutilizado

Los tokens reCAPTCHA son válidos para un solo uso y caducan después de aproximadamente 2 minutos. Si su automatización tarda demasiado entre recibir el token y enviar el formulario, o si reutiliza un token, la página de destino lo rechaza silenciosamente.

Errores en la etapa de solicitud (en.php)

Estos errores ocurren cuando envía la tarea CAPTCHA a https://ocr.captchaai.com/in.php.

Ejemplo: solicitud correcta con manejo de errores

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://staging.example.com/qa-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://staging.example.com/qa-login");
console.log(`Task submitted: ${taskId}`);

Errores en la etapa de resultados (res.php)

Estos errores ocurren al sondear https://ocr.captchaai.com/res.php para obtener el resultado.

Ejemplo: sondeo con manejo adecuado de errores

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`);
}

Rechazos de página de destino

La API devolvió un token válido pero el sitio de destino aún lo rechaza. Estos son los fallos más difíciles de depurar porque la API cree que todo funcionó.

Token inyectado en el campo equivocado

Algunas páginas buscan el token en el área de texto g-recaptcha-response. Otros usan grecaptcha.getResponse(). Otros esperan una devolución de llamada. Si elige el método de inyección incorrecto, el envío del formulario falla silenciosamente.

Solución: Inspeccione la página para determinar la ruta esperada:

# 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()

Callback no activado

Si el widget tiene data-callback="onSuccess" o usa grecaptcha.render() con una propiedad callback, llenar el campo oculto por sí solo no hace nada. Debes llamar a la función callback directamente.

Solución: Busca y llama al callback:

// 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);
}

Token caducado

Si pasan más de ~2 minutos entre la recepción del token y el envío del formulario, Google lo rechaza. Esto es común en procesos de automatización lentos.

Solución: Envíe el formulario inmediatamente después de recibir el token. Si su proceso es lento, solicite la solución más cerca del paso de envío en lugar de al principio.

El widget está en un iframe.

Si el reCAPTCHA se carga dentro de un iframe de un dominio diferente, debe usar la URL de origen del iframe como pageurl, no la URL de la página principal. El error ERROR_BAD_TOKEN_OR_PAGEURL suele indicar este problema.

Solución: Inspeccione la página, busque el iframe que contiene reCAPTCHA y use la URL src de ese iframe como su pageurl.

Lista de verificación de diagnóstico rápido

Preguntas frecuentes

¿Por qué falla reCAPTCHA v2 incluso cuando la solicitud parece correcta?

Las tres causas más comunes son: (1) pageurl no coincide con el contexto real del widget, especialmente cuando el widget está dentro de un iframe, (2) la página espera una función callback pero solo completaste el campo oculto, o (3) el token expiró antes de enviar el formulario.

¿Cuál es el error más común al resolver reCAPTCHA v2?

Usar el googlekey incorrecto o el pageurl incorrecto. Esto es especialmente común cuando el widget reCAPTCHA se carga en un iframe de un dominio o subdominio diferente: la sitekey y la URL deben coincidir con el contexto del iframe, no con la página principal.

¿Qué significa CAPCHA_NOT_READY?

Significa que el CAPTCHA todavía se está resolviendo. Esto no es un error. Espera 5 segundos y vuelve a sondear res.php. Los tiempos típicos de resolución de reCAPTCHA v2 son de 15 a 60 segundos.

¿Qué debo hacer si la API devuelve un token pero la página aún lo rechaza?

Verifica tres cosas en orden: (1) ¿La página utiliza un callback? Busca data-callback en el widget. (2) ¿Tu pageurl es correcto, especialmente si el widget está en un iframe? (3) ¿Pasaron más de 2 minutos entre la recepción y el uso del token?

¿Cómo manejo ERROR_CAPTCHA_UNSOLVABLE?

Envía una nueva tarea con parámetros nuevos. No vuelvas a intentar el mismo ID de tarea. Si este error ocurre repetidamente, verifica que la sitekey y la pageurl coincidan con la página real y que el tipo CAPTCHA sea reCAPTCHA v2 estándar (no Enterprise, que requiere parámetros diferentes).

Optimiza tu workflow de reCAPTCHA v2

1. Verifica tus entradas: extrae googlekey de data-sitekey y usa la URL de la página exacta (verifica si hay iframes)
2. Verifica el método de inyección: determina si la página espera un campo oculto, un callback o ambos.
3. Envía de inmediato: usa el token dentro de los 2 minutos posteriores a su recepción
4. Agrega manejo de errores: usa los ejemplos de código anteriores para detectar y manejar cada tipo de error

Comienza a resolver reCAPTCHA v2 con el solucionador CaptchaAI. Obtén tu clave API en captchaai.com/api.php.

Guías relacionadas

• Cómo resolver reCAPTCHA v2 usando la API — tutorial completo paso a paso
• Cómo resolver el callback de reCAPTCHA v2 usando la API — guía específica de callbacks
• Errores comunes de reCAPTCHA v2 Enterprise — errores específicos de Enterprise
• Referencia de códigos de error CaptchaAI — lista completa de códigos de error