Как исправить ошибки при решении капчи

При работе с API нашего сервиса одна из самых распространённых проблем — капча, которая не проходит валидацию: задача зависает в processing, возвращается invalid token, либо сайт отклоняет решение без очевидной причины.

В большинстве случаев это не связано с нашим сервисом. Ошибки возникают на стороне интеграции: неправильно извлечённые параметры, несоответствие сессии, некорректный тип задачи или нарушения таймингов при отправке токена.

В этой статье разобраны типичные причины, по которым капча не решается или не проходит проверку, а также практические способы их диагностики и устранения с учётом особенностей API нашего сервиса.

Неправильный websiteKey

Одна из самых частых причин ошибок. Если websiteKey указан неверно, наш сервис вернёт ERROR_RECAPTCHA_INVALID_SITEKEY или задача не будет решена.

Признаки:

• ответ API содержит errorId: 31 или код ERROR_RECAPTCHA_INVALID_SITEKEY
• капча остаётся в статусе processing и не переходит в ready
• целевой сайт отклоняет токен с ошибкой верификации

Как проверить:

• откройте исходный код страницы и найдите data-sitekey внутри g-recaptcha, cf-turnstile
• для reCAPTCHA ключ также может передаваться в параметре k в запросах к recaptcha/api.js
• убедитесь, что значение скопировано без пробелов и лишних символов

Неверный websiteURL

Наш сервис привязывает решение капчи к адресу страницы. Если websiteURL указан неверно, токен может быть недействителен для целевого сайта.

Особенно важно для:

• reCAPTCHA (v2, v3, enterprise)
• Cloudflare Turnstile

Правила передачи:

• указывайте полный URL с протоколом: https://example.com/page
• учитывайте поддомены: www.example.com и example.com — разные сайты с точки зрения капчи
• для динамических сайтов проверяйте финальный URL после редиректов

Ошибка в этом параметре часто приводит к коду ERROR_PAGEURL в ответе API.

Проблемы с прокси

Для некоторых типов капч и сайтов критически важны качественные прокси. Наш сервис поддерживает два подхода:

• Proxyless-задачи (например, RecaptchaV2TaskProxyless) — прокси используются на стороне сервиса
• Proxy-задачи (например, RecaptchaV2Task) — вы передаёте свои прокси через proxyAddress, proxyPort, proxyType

Признаки проблем:

• код ошибки ERROR_BAD_PROXY
• капча формально решается, но токен отклоняется сайтом
• капча появляется при каждом запросе

Рекомендации:

• используйте резидентские или мобильные прокси для сложных сайтов
• избегайте публичных дата-центровых диапазонов
• проверяйте стабильность и репутацию прокси

Просроченный токен

Токены капчи имеют ограниченное время жизни, обычно 1–2 минуты. При задержке в отправке на целевой сайт токен становится недействительным.

Как избежать:

• используйте токен сразу после получения статуса ready
• не кэшируйте решения между сессиями
• при задержках логики запрашивайте новую капчу через createTask

Слишком быстрые запросы к API

Частый опрос getTaskResult может привести к лимитам или таймаутам. Рекомендуемый интервал — 3–5 секунд.

Последствия:

• временные блокировки по IP
• ошибки timeout или rate limit
• увеличение времени решения задачи

Рекомендации:

• соблюдайте интервал 3–5 секунд при ручном опросе
• используйте pingback для автоматической доставки результата
• корректно обрабатывайте статус processing

Ошибки callback и вставки токена

Полученный токен необходимо корректно передать на целевой сайт. Простая вставка не всегда достаточна.

Пример для reCAPTCHA v2/v3:

document.getElementById('g-recaptcha-response').value = 'TOKEN';
document.querySelector('form').submit();

Пример для Turnstile:

document.querySelector('[name="cf-turnstile-response"]').value = 'TOKEN';

Если используется callback-функция, необходимо вызвать её, а не только установить значение.

Признаки ошибки:

• форма не отправляется
• сайт возвращает invalid token или verification failed
• ошибки в консоли браузера

Неправильный тип задачи в API

Наш сервис поддерживает разные типы капч, и для каждой требуется корректный type:

Если тип указан неверно, возможны ошибки ERROR_TASK_NOT_SUPPORTED или ERROR_BAD_PARAMETERS.

Как определить тип:

• проверьте классы виджетов: g-recaptcha, cf-turnstile
• посмотрите загружаемые скрипты в Network
• используйте документацию по определению CAPTCHA

Динамическая загрузка капчи

На современных сайтах капча часто загружается только после действий пользователя.

Признаки:

• виджет отсутствует в исходном HTML
• капча появляется после клика или логина
• параметры передаются через JavaScript

Решение:

• дождаться появления элемента перед созданием задачи
• отслеживать сетевые запросы
• использовать явные ожидания в коде

Ошибки работы с cookies и сессией

Некоторые антибот-системы привязывают капчу к сессии. При несоответствии cookies или IP токен отклоняется.

Проверки:

• совпадают ли cookies при создании задачи и отправке токена
• сохраняется ли сессия между шагами
• совпадает ли user-agent

В нашем сервисе можно передавать cookies через параметр:

key1=value1; key2=value2

Неправильная обработка ошибок API

Наш сервис возвращает подробные коды ошибок:

Всегда проверяйте errorId: 0 означает успех, любое другое значение — ошибка.

Заключение

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

Быстрая диагностика

Основные принципы интеграции

1. всегда определяйте тип капчи по фактическим данным страницы
2. не изменяйте извлечённые параметры вручную
3. соблюдайте единую сессию (cookies, IP, user-agent)
4. учитывайте лимиты API и сайта
5. логируйте ошибки и проверяйте errorId

Если проблема не решается

• включите логирование запросов API
• протестируйте задачу в личном кабинете
• проверьте доступность сайта из разных регионов
• обратитесь в поддержку с примером запроса и ответа

Правильная интеграция — это последовательная работа с деталями: от анализа страницы до корректной передачи токена.