Обработка ошибок
Стратегия опроса и повторов
- Опрашивайте
/res.phpне чаще раза в 5 секунд — пока приходитCAPCHA_NOT_READY, просто повторяйте запрос - При временных сетевых ошибках (обрыв соединения, 5xx) — повторите запрос через ~10 секунд
- При ошибках параметров (
ERROR_WRONG_*,ERROR_PAGEURL,ERROR_BAD_PARAMETERS) — сначала исправьте запрос, повтор без изменений результата не даст - Ограничивайте число повторов и общее время ожидания на задачу — это защищает от лишних трат при зависшей капче
- Логируйте код ошибки вместе с параметрами запроса (метод,
task_id) — это ускоряет разбор проблем
Общие ошибки
Эти ошибки могут возникнуть при работе с любым методом API.
| Код | Описание |
|---|---|
ERROR_WRONG_USER_KEY | Неверный формат API-ключа. Проверьте свой API-ключ (32 символа) |
ERROR_KEY_DOES_NOT_EXIST | Такого API-ключа не существует. Проверьте правильность ключа |
ERROR_ZERO_BALANCE | Недостаточно средств на балансе. Пополните счёт, чтобы продолжить |
ERROR_PAGEURL | Отсутствует параметр pageurl. Укажите полный URL страницы |
ERROR_WRONG_ID_FORMAT | Неверный формат id при запросе результата — должен состоять только из цифр |
ERROR_CAPTCHA_UNSOLVABLE | Капча не может быть решена. Проверьте корректность параметров и тип капчи |
IP_BANNED | Ваш IP временно заблокирован. Подождите около 5 минут |
CAPCHA_NOT_READY | Решение ещё не готово. Подождите 5 секунд и повторите запрос |
Специфичные для метода
| Код | Метод | Описание |
|---|---|---|
ERROR_WRONG_GOOGLEKEY | reCAPTCHA V2 / V3 (и Enterprise-версии) | sitekey пустой или в неверном формате |
ERROR_BAD_TOKEN_OR_PAGEURL | reCAPTCHA V2 | Неверная пара googlekey/pageurl. Проверьте, что reCAPTCHA не в iframe |
ERROR_WRONG_CAPTCHA_ID | GeeTest V3 / CaptchaFox / BLS | Неверный gt/challenge, sitekey или id задачи |
ERROR_WRONG_SITEKEY | Cloudflare Turnstile | sitekey пустой или в неверном формате |
ERROR_BAD_PROXY | Turnstile / Cloudflare Challenge / CaptchaFox | Прокси помечен как нерабочий или недоступен |
ERROR_PROXY_CONNECTION_FAILED | Turnstile / Cloudflare Challenge / CaptchaFox | Не удалось подключиться через указанный прокси — попробуйте другой |
ERROR_WRONG_FILE_EXTENSION | Обычная капча / Grid Image | Неподдерживаемый формат файла — используйте JPG, JPEG, PNG или GIF |
ERROR_ZERO_CAPTCHA_FILESIZE | Обычная капча / Grid Image | Файл пустой или повреждён |
ERROR_TOO_BIG_CAPTCHA_FILESIZE | Обычная капча / Grid Image | Файл превышает 100 КБ |
ERROR_BAD_PARAMETERS | Grid Image / BLS Captcha | Проверьте grid_size/instructions/img_type (Grid) или изображения/instructions (BLS) |
Подробности по каждому методу — на соответствующей странице в разделе «Виды капч».