Распространенные ошибки и исправления reCAPTCHA v2

Большинство сбоев reCAPTCHA v2 делятся на три группы: ошибки на этапе запроса (неправильные параметры, отправленные в API), проблемы на этапе результата (проблемы опроса или неразрешимые задачи) и отклонение целевой страницы (API возвращает действительный токен, но страница его игнорирует). Главные виновники почти всегда одни и те же: неправильный googlekey, неправильный pageurl, отсутствие выполнения обратного вызова или токены с истекшим сроком действия.

В этом руководстве описаны все распространенные модели сбоев и указаны точные способы устранения каждой из них. Если вы новичок в решении reCAPTCHA v2, прочитайтеКак решить reCAPTCHA v2 с помощью APIпервый.

Четыре самые большие точки отказа reCAPTCHA v2

Прежде чем копаться в отдельных кодах ошибок, сначала проверьте их — они охватывают 80% сбоев.

1. Неправильный или отсутствует googlekey.

googlekey (ключ сайта) берется из атрибута data-sitekey виджета reCAPTCHA или параметра k в URL-адресе привязки. Если это значение неверно, пусто или скопировано с другой страницы, API немедленно отклоняет задачу с помощью ERROR_GOOGLEKEY или ERROR_WRONG_GOOGLEKEY.

Как найти правильный ключ сайта:

# 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

pageurl должен быть точным URL, по которому загружается виджет reCAPTCHA. Если виджет находится внутри iframe, размещенного в другом домене, вам нужен URL-адрес iframe, а не URL-адрес родительской страницы. Отправка неправильного URL-адреса приводит к возникновению ERROR_PAGEURL или ERROR_BAD_TOKEN_OR_PAGEURL.

3. Обратный вызов не выполнен.

На некоторых страницах вместо скрытого поля g-recaptcha-response используется функция обратного вызова JavaScript. Если вы введете токен в скрытое поле, но страница ожидает обратного вызова, форма никогда не будет отправлена. Проверьте наличие data-callback в виджете или свойство callback в grecaptcha.render().

4. Срок действия токена истек или он использовался повторно.

Токены reCAPTCHA действительны для только одного использования и истекают через около 2 минут. Если ваша автоматизация проходит слишком много времени между получением токена и отправкой формы или если она повторно использует токен, целевая страница автоматически отклоняет его.

Ошибки на этапе запроса (in.php)

Эти ошибки возникают, когда вы отправляете задачу CAPTCHA в https://ocr.captchaai.com/in.php.

Пример: правильный запрос с обработкой ошибок

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

Ошибки на этапе результата (res.php)

Эти ошибки возникают при опросе https://ocr.captchaai.com/res.php для получения результата.

Пример: опрос с правильной обработкой ошибок

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

Отклонение целевой страницы

API вернул действительный токен, но целевой сайт по-прежнему отклоняет его. Это самые трудные ошибки для отладки, поскольку API считает, что все работает.

Токен введен не в то поле

На некоторых страницах токен ищется в текстовой области g-recaptcha-response. Другие используют grecaptcha.getResponse(). Другие ожидают обратного звонка. Если вы выберете неправильный метод внедрения, отправка формы завершится с ошибкой.

Исправление. Проверьте страницу, чтобы определить ожидаемый путь:

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

Обратный звонок не запущен

Если виджет имеет data-callback="onSuccess" или использует grecaptcha.render() со свойством 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);
}

Срок действия токена истек

Если между получением токена и отправкой формы проходит более двух минут, Google отклоняет ее. Это часто встречается в медленных конвейерах автоматизации.

Исправление: Отправьте форму сразу после получения токена. Если ваш конвейер работает медленно, запросите решение ближе к этапу отправки, а не в начале.

Виджет находится в iframe

Если reCAPTCHA загружается внутри iframe из другого домена, вы должны использовать URL-адрес источника iframe как pageurl, а не URL-адрес родительской страницы. Ошибка ERROR_BAD_TOKEN_OR_PAGEURL обычно сигнализирует об этой проблеме.

Исправление: проверьте страницу, найдите iframe, содержащий reCAPTCHA, и используйте URL-адрес src этого iframe в качестве pageurl.

Контрольный список быстрой диагностики

Часто задаваемые вопросы

Почему reCAPTCHA v2 завершается с ошибкой, даже если запрос выглядит правильно?

Три наиболее распространенные причины: (1) pageurl не соответствует фактическому контексту виджета — особенно, когда виджет находится внутри iframe, (2) страница ожидает функцию обратного вызова, но вы заполнили только скрытое поле, или (3) срок действия токена истек до того, как вы отправили форму.

Какова наиболее распространенная ошибка при решении reCAPTCHA v2?

Использование неправильного googlekey или неправильного pageurl. Это особенно распространено, когда виджет reCAPTCHA загружается в iframe в другом домене или субдомене — ключ сайта и URL-адрес должны соответствовать контексту iframe, а не родительской странице.

Что означает CAPCHA_NOT_READY?

Это означает, что CAPTCHA все еще решается. Это не ошибка. Подождите 5 секунд и снова опросите res.php. Типичное время решения reCAPTCHA v2 составляет 15–60 секунд.

Что делать, если API возвращает токен, но страница по-прежнему его отклоняет?

Проверьте три вещи по порядку: (1) Использует ли страница обратный вызов? Найдите data-callback на виджете. (2) Верен ли ваш pageurl, особенно если виджет находится в iframe? (3) Между получением и использованием токена прошло более 2 минут?

Как мне справиться с ERROR_CAPTCHA_UNSOLVABLE?

Отправьте новую задачу с новыми параметрами. Не повторяйте тот же идентификатор задачи. Если эта ошибка повторяется, убедитесь, что ваш ключ сайта и URL-адрес страницы соответствуют фактической странице и что тип CAPTCHA является стандартным reCAPTCHA v2 (не Enterprise — для которого требуются другие параметры).

Исправьте рабочий процесс reCAPTCHA v2

1. Подтвердите введенные данные — извлеките googlekey из data-sitekey и используйте точный URL-адрес страницы (проверьте наличие iframe).
2. Проверьте метод внедрения — определите, ожидает ли страница скрытое поле, обратный вызов или и то, и другое.
3. Отправить немедленно — используйте токен в течение 2 минут с момента его получения.
4. Добавьте обработку ошибок — используйте приведенные выше примеры кода, чтобы перехватывать и обрабатывать ошибки каждого типа.

Начните решать reCAPTCHA v2 с помощьюРешатель CaptchaAI. Получите ключ API отcaptchaai.com/api.php.

Связанные руководства

• Как решить reCAPTCHA v2 с помощью API— полное пошаговое руководство
• Как решить обратный вызов reCAPTCHA v2 с помощью API— руководство по обратному вызову
• Объяснение проблемы сетки reCAPTCHA— как работают задачи сетки
• Справочник кодов ошибок CaptchaAI— полный список кодов ошибок