Resolvendo erros e correções comuns do reCAPTCHA v2

A maioria das falhas do reCAPTCHA v2 se enquadra em três grupos: erros no estágio de solicitação (parâmetros errados enviados para a API), problemas no estágio de resultado (problemas de pesquisa ou tarefas insolúveis) e rejeições na página de destino (a API retorna um token válido, mas a página o ignora). Os maiores culpados são quase sempre os mesmos: googlekey errado, pageurl incorreto, falta de execução de retorno de chamada ou tokens expirados.

Este guia aborda cada padrão de falha comum com a solução exata para cada um. Se você é novo na resolução de reCAPTCHA v2, leiaComo resolver reCAPTCHA v2 usando APIprimeiro.

Os quatro maiores pontos de falha do reCAPTCHA v2

Antes de se aprofundar nos códigos de erro individuais, verifique-os primeiro – eles cobrem 80% das falhas.

1. googlekey errado ou ausente

O googlekey (sitekey) vem do atributo data-sitekey no widget reCAPTCHA ou do parâmetro k no URL âncora. Se este valor estiver errado, em branco ou copiado de uma página diferente, a API rejeita a tarefa imediatamente com ERROR_GOOGLEKEY ou ERROR_WRONG_GOOGLEKEY.

Como encontrar a chave do site correta:

# 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 errado

O pageurl deve ser o URL exato onde o widget reCAPTCHA é carregado. Se o widget estiver dentro de um iframe hospedado em um domínio diferente, você precisará do URL do iframe, e não do URL da página pai. Enviar o URL errado causa ERROR_PAGEURL ou ERROR_BAD_TOKEN_OR_PAGEURL.

3. Retorno de chamada não executado

Algumas páginas usam uma função de retorno de chamada JavaScript em vez do campo g-recaptcha-response oculto. Se você injetar o token no campo oculto, mas a página esperar um retorno de chamada, o formulário nunca será enviado. Verifique data-callback no widget ou uma propriedade callback em grecaptcha.render().

4. Token expirou ou foi reutilizado

Os tokens reCAPTCHA são válidos para apenas um uso e expiram após cerca de 2 minutos. Se sua automação demorar muito entre o recebimento do token e o envio do formulário, ou se reutilizar um token, a página de destino o rejeitará silenciosamente.

Erros no estágio de solicitação (in.php)

Esses erros acontecem quando você envia a tarefa CAPTCHA para https://ocr.captchaai.com/in.php.

Exemplo: solicitação correta com tratamento de erros

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

Erros na fase de resultados (res.php)

Esses erros acontecem ao pesquisar o resultado em https://ocr.captchaai.com/res.php.

Exemplo: Pesquisa com tratamento de erros adequado

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

Rejeições de páginas de destino

A API retornou um token válido, mas o site de destino ainda o rejeita. Estas são as falhas mais difíceis de depurar porque a API pensa que tudo funcionou.

Token injetado no campo errado

Algumas páginas procuram o token na área de texto g-recaptcha-response. Outros usam grecaptcha.getResponse(). Outros esperam um retorno de chamada. Se você escolher o método de injeção errado, o envio do formulário falhará silenciosamente.

Correção: Inspecione a página para determinar o caminho esperado:

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

Retorno de chamada não acionado

Se o widget tiver data-callback="onSuccess" ou usar grecaptcha.render() com uma propriedade callback, preencher apenas o campo oculto não fará nada. Você deve chamar a função de retorno de chamada diretamente.

Correção: Encontre e ligue para o retorno de chamada:

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

O token expirou

Se passarem mais de 2 minutos entre o recebimento do token e o envio do formulário, o Google o rejeitará. Isso é comum em pipelines de automação lentos.

Correção: Envie o formulário imediatamente após receber o token. Se o seu pipeline for lento, solicite a solução mais perto da etapa de envio, e não no início.

O widget está em um iframe

Se o reCAPTCHA for carregado dentro de um iframe de um domínio diferente, você deverá usar o URL de origem do iframe como pageurl, não o URL da página pai. O erro ERROR_BAD_TOKEN_OR_PAGEURL geralmente sinaliza esse problema.

Correção: Inspecione a página, encontre o iframe que contém o reCAPTCHA e use o URL src desse iframe como seu pageurl.

Lista de verificação de diagnóstico rápido

Perguntas frequentes

Por que reCAPTCHA v2 falha mesmo quando a solicitação parece correta?

As três causas mais comuns são: (1) o pageurl não corresponde ao contexto real do widget — especialmente quando o widget está dentro de um iframe, (2) a página espera uma função de retorno de chamada, mas você preencheu apenas o campo oculto ou (3) o token expirou antes de você enviar o formulário.

Qual é o erro de resolução reCAPTCHA v2 mais comum?

Usando o googlekey errado ou pageurl errado. Isso é especialmente comum quando o widget reCAPTCHA é carregado em um iframe em um domínio ou subdomínio diferente – a chave do site e o URL devem corresponder ao contexto do iframe, não à página pai.

O que significa CAPCHA_NOT_READY?

Isso significa que o CAPTCHA ainda está sendo resolvido. Isto não é um erro. Aguarde 5 segundos e pesquise res.php novamente. Os tempos de resolução típicos do reCAPTCHA v2 são de 15 a 60 segundos.

O que devo fazer se a API retornar um token, mas a página ainda o rejeitar?

Verifique três coisas em ordem: (1) A página usa retorno de chamada? Procure data-callback no widget. (2) O seu pageurl está correto - especialmente se o widget estiver em um iframe? (3) Passaram mais de 2 minutos entre o recebimento e o uso do token?

Como faço para lidar com ERROR_CAPTCHA_UNSOLVABLE?

Envie uma nova tarefa com novos parâmetros. Não tente novamente o mesmo ID de tarefa. Se esse erro ocorrer repetidamente, verifique se a chave do site e o URL da página correspondem à página real e se o tipo de CAPTCHA é o padrão reCAPTCHA v2 (não Enterprise - que requer parâmetros diferentes).

Corrija seu fluxo de trabalho reCAPTCHA v2

1. Verifique suas entradas — extraia googlekey de data-sitekey e use o URL exato da página (verifique se há iframes)
2. Verifique o método de injeção — determine se a página espera campo oculto, retorno de chamada ou ambos
3. Envie imediatamente — use o token dentro de 2 minutos após recebê-lo
4. Adicione tratamento de erros — use os exemplos de código acima para capturar e tratar cada tipo de erro

Comece a resolver reCAPTCHA v2 com oSolucionador CaptchaAI. Obtenha sua chave de API emcaptchaai.com/api.php.

Guias relacionados

• Como resolver reCAPTCHA v2 usando API- tutorial passo a passo completo
• Como resolver o retorno de chamada reCAPTCHA v2 usando API— guia específico de retorno de chamada
• Desafio da grade reCAPTCHA explicado— como funcionam os desafios da rede
• Referência de códigos de erro CaptchaAI— lista completa de códigos de erro