Эта статья была полезной?
Как исправить самые частые ошибки интеграции API для капч
Технический специалист
Практически любая интеграция спотыкается об одни и те же грабли, обычно в первую же неделю. Копируете код из примера, подставляете свой API-ключ, запускаете — и получаете ошибку, которой нет в quick-start гайде. В девяти случаях из десяти это не баг в SDK, а одна из горстки типичных ошибок, которые легко чинятся, как только понимаешь, что на самом деле пошло не так.
Вот десять, с которыми сталкиваются чаще всего — примерно в том порядке, в котором на них натыкаются.
1. Неверный или отсутствующий API-ключ
Проявляется как ERROR_WRONG_USER_KEY или ERROR_KEY_DOES_NOT_EXIST. В девяти случаях из десяти это проблема копипаста — лишний пробел в конце ключа, случайно захваченные кавычки, или ключ не из того аккаунта (тестовый вместо продакшена, или ключ коллеги, который переслали в Slack и вставили вместе с переносом строки). Выведите ключ прямо перед отправкой запроса и сравните его длину с тем, что показано в личном кабинете. Если всё равно не совпадает — проще сгенерировать новый ключ и подставить его.
2. Нулевой баланс
ERROR_ZERO_BALANCE означает ровно то, что написано — на счёте не осталось денег на оплату решений. Чинится это просто, но в продакшене подводит неожиданно: скрипт, который прекрасно работал, вдруг начинает падать без единого изменения в коде. Если что-то работает без присмотра, стоит настроить уведомление о балансе или хотя бы периодически его проверять — чтобы не узнавать об этом в три ночи.
3. ERROR_CAPTCHA_UNSOLVABLE
Это значит, что капча реально не поддавалась решению — не баг на вашей стороне, а обычно проблема с качеством данных. Для капч на основе изображений причина часто в обрезанном или повреждённом скриншоте, в изображении капчи, которое успело "протухнуть" до отправки, или в шаге base64-кодирования, который испортил картинку. Для токен-based капч вроде reCAPTCHA или Turnstile это может значить, что отправленные sitekey или URL страницы на самом деле не соответствуют живому, рабочему виджету капчи. Стоит перепроверить, что отправляемые параметры точно совпадают с тем, что реально отрисовано на странице.
4. Неверный sitekey
Связано с предыдущим пунктом, но встречается достаточно часто, чтобы вынести отдельно. Люди нередко берут не тот sitekey, если на странице несколько виджетов капчи, либо достают его из закэшированной версии страницы, которая с тех пор изменилась. Извлекайте sitekey заново, прямо перед использованием, из атрибута data-sitekey на живой странице или из сетевого запроса, который загружает виджет — и никогда не хардкодьте значение из прошлой сессии.
5. Слишком частый опрос результата или таймаут
Если вы опрашиваете результат сами, а не через метод SDK, который делает это за вас, долбить эндпоинт результата каждую секунду-две обычно просто тратит запросы впустую — капчи решаются в среднем за 10–20 секунд, а сложные типы и дольше. Опрашивайте раз в 5 секунд и дайте разумный таймаут (минуту-две, а не пять секунд) прежде чем решить, что что-то реально сломалось. Большинство SDK берут этот цикл опроса на себя, так что если вы пишете его вручную — сначала стоит проверить, точно ли это нужно.
6. Токен получен, но форма всё равно его не принимает
Почти всегда причина одна из двух: токен подставлен не в то поле, либо сайт ждёт срабатывания своей JavaScript callback-функции, а вы только выставили значение поля, но саму функцию не вызвали. Проверьте атрибут data-callback виджета (или вызов render() в исходном коде страницы), чтобы найти правильное имя функции, и вызовите её напрямую с токеном — вместо простой установки значения скрытого поля или вместе с ней.
7. Локально всё работает, на сервере — нет
Тот же код, тот же ключ, разный результат — и дело тут редко в самом API. Почти всегда причина в IP-адресе сервера. Датацентровые IP многие антибот-системы помечают ещё до того, как вообще успевает загрузиться капча, из-за чего либо показывается более сложная проверка, либо запрос блокируется целиком. Если с локальной машины всё проходит, а с сервера — нет, попробуйте пустить трафик сервера через residential или мобильный прокси и посмотреть, изменится ли что-то.
8. Токен истёк раньше, чем его успели использовать
Решённые токены не живут вечно — токены reCAPTCHA действительны примерно две минуты, у других типов свои лимиты. Если между получением токена и отправкой формы проходит много времени (ожидание других шагов, retry-логика, медленная загрузка страницы), токен может протухнуть ещё до того, как его вообще использовали. Держите промежуток между "получил токен" и "отправил форму" максимально коротким, а если отправка не удалась — берите новый токен, а не пытайтесь переиспользовать старый.
9. Pingback или webhook не срабатывает
Если вы настроили pingback, чтобы API само уведомляло ваш сервер о решении капчи вместо опроса результата, а уведомления не приходят — проверьте, что callback-URL действительно доступен из интернета, а не только с localhost или из внутренней сети. Обычно виноваты файрвол или NAT. Быстрый способ проверить: постучитесь на этот URL сами из внешнего инструмента и убедитесь, что он отвечает так, как ожидается.
10. Упёрлись в лимит запросов под нагрузкой
Отправите слишком много запросов одновременно — получите ERROR_NO_SLOT_AVAILABLE или похожую ошибку троттлинга. Обычно всплывает при масштабировании скрипта, который прекрасно работал на малых объёмах. Решение — обычно добавить очередь или ограничение по параллельности на своей стороне, а не отправлять всё разом: распределяйте запросы во времени, а если всё же упёрлись в лимит — делайте паузу и повторяйте попытку.
Если ничего из этого не похоже на вашу ошибку
Кодов ошибок гораздо больше, чем перечислено здесь — полная таблица со всеми кодами и коротким объяснением каждого лежит в документации API. Стоит добавить её в закладки: у новых интеграций почти всегда вылезает хотя бы одна ошибка, которой нет в списке выше.