Справочник API

Коды ошибок

Эта страница переведена с китайской версии машинным переводом и может содержать ошибки. Приоритет имеет китайская версия.

При ошибке API возвращает errorId: 1; errorCode содержит код ошибки, errorDescription — текстовое описание. За запросы, вернувшие ошибку, баллы не списываются: если ошибка возникла при создании задачи, списания нет, а если распознавание не удалось или истекло время после создания, баллы возвращаются автоматически.

{
  "errorId": 1,
  "errorCode": "ERROR_ZERO_BALANCE",
  "errorDescription": "帐户余额不足"
}

Как обрабатывать ошибки

Ошибки параметров (формат запроса, ClientKey, тип задачи, параметры сайта, изображения) не исчезнут при повторной отправке — сначала исправьте запрос.
Неудачное распознавание и тайм-аут (ERROR_CAPTCHA_UNSOLVABLE, ERROR_TASK_TIMEOUT) можно повторить, создав задачу заново.
После ошибки прекратите опрос (polling) этого taskId и не отправляйте тот же запрос повторно с высокой частотой.
Ошибки с пометкой «Учитывается в приостановке»: если для одного clientKey набирается 100 таких ошибок за минуту, создание задач приостанавливается на 5 минут. Ошибки с пометкой «Кэшируется» в этот счётчик не входят, но пока действует кэш, одинаковые запросы сразу получают прежнюю ошибку. Подробнее — в разделе Лимит параллельных задач и автоматическая приостановка.

Все коды ошибок

Формат запроса

Код ошибки	Значение	Что делать
`ERROR_REQUIRED_FIELDS`	Отсутствует обязательное поле (например, `clientKey` или `websiteURL` / `websiteKey` для данного типа задачи), либо тело запроса не является JSON	Добавьте недостающие поля, перечисленные на странице типа задачи, и отправляйте JSON методом `POST` с заголовком `Content-Type: application/json`
`ERROR_REQUEST_FORMATS` Учитывается для автоматической приостановки	Тело запроса не является корректным JSON	Формируйте тело запроса с помощью JSON-библиотеки, а не конкатенацией строк; в JSON не должно быть комментариев `//`
`ERROR_TASK_ABSENT` Учитывается для автоматической приостановки	В вызове `createTask` отсутствует поле `task`	Поместите параметры задачи в объект `task`. В Python requests используйте `json=data`, а не `data=data`
`ERROR_TASK_NOT_SUPPORTED` Учитывается для автоматической приостановки	В `task.type` допущена опечатка, либо этот тип отключён	Скопируйте название типа из раздела «Типы задач и цены»; регистр важен
`ERROR_PAGE_NOT_FOUND`	Запрошенный путь не существует	Проверьте адрес endpoint, например `https://api.yescaptcha.com/createTask`; названия методов чувствительны к регистру
`ERROR_BAD_REQUEST`	Запрос не может быть обработан, обычно из-за неверного HTTP-метода (GET вместо POST) или недопустимых значений параметров	Отправляйте JSON методом `POST` и проверьте типы и значения параметров
`ERROR_ILLEGAL_PARAMETERS`	Недопустимое значение параметра. Типично для страницы проверки Cloudflare: `websiteURL` не является публичным URL, начинающимся с `http://` / `https://`, `postData` не является объектом, либо `requiredCookies` не является массивом строк (возвращается `createTask`, списание баллов не производится); либо не удалось разрешить домен целевого сайта через прокси (возвращается `getTaskResult`, возврат баллов выполняется автоматически)	Исправьте значение в соответствии с таблицей параметров на странице типа задачи. Если домен не удалось разрешить, проверьте написание URL и то, может ли прокси подключиться к сайту

Аккаунт и баланс

Код ошибки	Значение	Что делать
`ERROR_KEY_DOES_NOT_EXIST` Учитывается для автоматической приостановки	`clientKey` не существует: при копировании были добавлены или потеряны символы, либо ключ был сброшен в Панели	Скопируйте ключ заново в Панели на yescaptcha.com, без пробелов и переносов строк
`ERROR_KEY_EXPIRED` Учитывается для автоматической приостановки	Срок действия `clientKey` истёк (возвращается при createTask и getBalance, списание баллов не производится). Возможны два случая: ключ долго не использовался, и система установила срок действия для защиты аккаунта (перед истечением срока приходит напоминание по электронной почте), либо истёк срок действия, заданный для этого `clientKey`	Войдите в Панель на yescaptcha.com. Если срок истёк из-за долгого неиспользования, создайте новый `clientKey`: Баланс автоматически перейдёт на новый ключ. Если срок действия был задан вручную, измените его или используйте другой `clientKey`. Затем обновите `clientKey` в своей программе
`ERROR_KEY_IP_NOT_ALLOWED`	Для этого `clientKey` задан белый список IP, и IP, с которого пришёл запрос, в нём отсутствует (возвращается при createTask и getBalance, списание баллов не происходит, в автоматическую приостановку не засчитывается)	Войдите в Панель на yescaptcha.com и добавьте публичный IP машины, отправляющей запросы, в белый список этого `clientKey`, либо используйте другой `clientKey`. Если API вызывается с нескольких машин, добавьте публичный IP каждой из них (имеется в виду IP, с которого вызывается API YesCaptcha, а не прокси в параметрах задачи)
`ERROR_KEY_QUOTA_EXCEEDED`	Для этого `clientKey` задан лимит расходов, и его остатка за текущий период меньше, чем стоимость этой задачи (возвращается при createTask, списание баллов не происходит, в автоматическую приостановку не засчитывается). В лимит засчитываются фактически списанные баллы; баллы, возвращённые за неудачные задачи или задачи с истекшим временем ожидания, возвращаются в лимит	Войдите в Панель на yescaptcha.com и увеличьте лимит этого `clientKey`, дождитесь следующего периода (лимит сбрасывается ежедневно, каждый понедельник или 1-го числа каждого месяца по пекинскому времени; разовый лимит не сбрасывается) либо используйте другой `clientKey`. Оставшийся лимит этого `clientKey` (`keyQuotaRemaining`) возвращает `getBalance`
`ERROR_ZERO_BALANCE`	Недостаточно баллов на балансе. Для создания задачи баланс должен быть больше 10 баллов	Пополните баланс и повторите попытку. Проверить баланс можно с помощью `getBalance`

Параллельные задачи и приостановки

Код ошибки	Значение	Что делать
`ERROR_THREADS_MAXIMUM` Иногда учитывается для автоматической приостановки	Для аккаунта одновременно выполняется слишком много задач этого типа. `limit` в ответе — текущий лимит параллельных задач. Запрос не был обработан, списание баллов не производилось	Дождитесь ответов на уже отправленные запросы или подождите 1–2 секунды и повторите; ограничьте в программе число одновременно ожидающих запросов
`ERROR_IP_BLOCKED_5MIN`	Этот `clientKey` за короткое время вызвал слишком много ошибок и был автоматически приостановлен. `retryAfter` — оставшееся время в секундах, `blockReason` — ошибка, вызвавшая приостановку	Исправьте запрос согласно `blockReason` и подождите `retryAfter` секунд; отправка запросов во время приостановки её не продлевает
`ERROR_NO_SLOT_AVAILABLE`	Сервис распознавания временно перегружен. Если ошибка возвращена методом createTask, баллы не списываются; если задача слишком долго ждала в очереди, ошибка также возвращается методом getTaskResult, а баллы возвращаются автоматически	Подождите несколько секунд и создайте задачу снова

Задачи и результаты

Код ошибки	Значение	Что делать
`ERROR_TASKID_INVALID` Учитывается для автоматической приостановки	`taskId` не существует, срок его действия истёк (результаты хранятся около 10 минут), он принадлежит другому `clientKey` или был создан на другом endpoint	Прекратите опрос (polling) этой задачи. Запрашивайте результат через тот же endpoint и с тем же `clientKey`, которые использовались при создании
`ERROR_TASK_TIMEOUT`	Задача не была выполнена за отведённое время (обычно 110 секунд); баллы возвращены автоматически	Создайте новую задачу; если таймауты повторяются, попробуйте другой тип задачи для той же капчи
`ERROR_CAPTCHA_UNSOLVABLE`	В этот раз капчу распознать не удалось; баллы возвращены. Эта ошибка не учитывается при автоматической приостановке	Создайте новую задачу. Если ошибка повторяется, проверьте `websiteURL`, `websiteKey` и другие параметры или попробуйте другой тип задачи для той же капчи
`ERROR_SETTLEMENT_FAILED` Учитывается для автоматической приостановки	На момент расчёта на балансе не хватило баллов, поэтому результат не был возвращён	Пополните баланс и создайте новую задачу
`ERROR_NO_SUCH_CAPCHA_ID`	Задача больше не действительна	Прекратите опрос (polling) этой задачи и создайте новую
`ERROR_RECAPTCHA_TIMEOUT`	Время распознавания капчи истекло; баллы возвращены	Создайте новую задачу

Параметры целевого сайта

Код ошибки	Значение	Что делать
`ERROR_RECAPTCHA_INVALID_SITEKEY` Кешируется, не ведёт к приостановке	`websiteKey` недействителен	Заново найдите sitekey на странице (см. руководства по поиску параметров). Идентичные запросы в течение срока кеширования сразу возвращают эту ошибку с `cached: true`
`ERROR_RECAPTCHA_INVALID_DOMAIN` Кешируется, не ведёт к приостановке	Домен в `websiteURL` не соответствует `websiteKey`	Укажите в `websiteURL` адрес страницы, на которой отображается капча
`ERROR_INVALID_KEY_TYPE` Кешируется, не ведёт к приостановке	Sitekey относится к другой капче, например ключ v3 использован с типом задачи для v2	Сначала определите тип капчи (см. «Определение типа капчи») и выберите соответствующий тип задачи; для невидимой версии v2 укажите `isInvisible`
`ERROR_DOMAIN_NOT_ALLOWED` Кешируется, не ведёт к приостановке	Этот сайт не поддерживается	Попробуйте другой тип задачи для той же капчи или обратитесь в поддержку
`ERROR_HIGH_DEMAND_DOMAIN` Учитывается для автоматической приостановки	Этот сайт не поддерживается	Прекратите отправлять задачи для этого сайта и обратитесь в поддержку
`ERROR_FAILED_LOADING_WIDGET`	Не удалось загрузить капчу с указанными параметрами	Проверьте `websiteURL` и `websiteKey`; для типов задач с собственным прокси убедитесь, что прокси имеет доступ к сайту

Изображения

Код ошибки	Значение	Что делать
`ERROR_ZERO_CAPTCHA_FILESIZE` Учитывается для автоматической приостановки	Изображение пустое или слишком маленькое	Убедитесь, что данные Base64 переданы полностью и без префикса `data:image/...;base64,`
`ERROR_TOO_BIG_CAPTCHA_FILESIZE` Учитывается для автоматической приостановки	Изображение слишком большое	Сожмите или уменьшите изображение; размер всего тела запроса не должен превышать 6 MB
`ERROR_IMAGE_TYPE_NOT_SUPPORTED` Учитывается для автоматической приостановки	Формат изображения не поддерживается или это изображение не подходит для данного типа задачи. Одного такого случая достаточно, чтобы приостановить ключ на 30 минут	Используйте JPG или PNG и убедитесь, что изображение соответствует типу задачи, например для распознавания изображений reCAPTCHA нужен размер 100x100, 300x300 или 450x450
`ERROR_ILLEGAL_IMAGE` Учитывается для автоматической приостановки	Размер изображения не соответствует требованиям этого типа задачи	Измените размер изображения согласно описанию на странице типа задачи
`ERROR_PARSE_IMAGE_FAIL`	Не удалось декодировать изображение, часто из-за того, что Base64 обрезан или содержит префикс	Проверьте кодировку Base64 и удалите префикс `data:` и переносы строк
`ERROR_UNKNOWN_QUESTION`	Значение `question` указано неверно или этот вопрос пока не поддерживается	Сверьтесь со списком вопросов на странице типа задачи. Если вопрос не поддерживается, обратитесь в поддержку; новые вопросы обычно добавляются в течение 3 рабочих дней
`ERROR_UNKNOW_450x450_QUESTION`	Этот вопрос пока не поддерживается для изображений 4x4 (450x450)	Обновите проверку на странице, чтобы получить другой вопрос

Прокси

Код ошибки	Значение	Что делать
`ERROR_PROXY_CONNECT_REFUSED`	Прокси отклонил подключение	Проверьте адрес, порт и протокол прокси и убедитесь, что он принимает внешние подключения (это не должен быть локальный адрес, например 127.0.0.1)
`ERROR_PROXY_CONNECT_TIMEOUT`	Время подключения к прокси истекло	Используйте более надёжный прокси
`ERROR_PROXY_READ_TIMEOUT`	Время чтения данных через прокси истекло	Используйте более быстрый прокси
`ERROR_PROXY_BANNED`	Прокси недоступен или его IP заблокирован целевым сайтом	Используйте другой прокси
`ERROR_PROXY_INCORRECT`	Параметры прокси имеют неверный формат	Проверьте формат `proxyType`, `proxyAddress`, `proxyPort` (или строки `proxy`)
`ERROR_PROXY_TRANSPARENT`	Прокси является прозрачным и раскрывает реальный IP	Используйте анонимный (элитный) прокси
`ERROR_PROXY_NOT_AUTHORISED`	Логин или пароль прокси указаны неверно	Проверьте `proxyLogin` и `proxyPassword` (или учётные данные в строке `proxy`)
`ERROR_PROXY_TLS_ERROR`	Не удалось выполнить TLS-рукопожатие с прокси, часто из-за неверного `proxyType` (например, указан https для http-прокси)	Проверьте протокол прокси
`ERROR_PROXY_CONNECTION_FAILED`	Не удалось подключиться к прокси-серверу	Проверьте адрес и порт прокси и убедитесь, что прокси работает

Сервер

Код ошибки	Значение	Что делать
`ERROR_SERVICE_UNAVALIABLE`	Сервис временно недоступен (в коде ошибки используется написание `UNAVALIABLE`)	Повторите попытку позже; если ошибка не исчезает, обратитесь в поддержку
`ERROR_INTERNAL_SERVER_ERROR`	Внутренняя ошибка сервера	Повторите попытку позже; если ошибка повторяется, обратитесь в поддержку и укажите `taskId`
`ERROR_UNKNOWN`	Неклассифицированная ошибка	Повторите попытку позже; если ошибка повторяется, обратитесь в поддержку и укажите `taskId`

Дополнительные поля

В ответах на некоторые ошибки есть дополнительные поля:

Поле	Где встречается	Описание
`retryAfter`	`ERROR_IP_BLOCKED_5MIN`, кэшированные ошибки	Сколько секунд осталось ждать
`blockReason`	`ERROR_IP_BLOCKED_5MIN`	Код ошибки, вызвавшей приостановку
`blockDetail`	`ERROR_IP_BLOCKED_5MIN`	Тип, URL и sitekey запросов, вызвавших приостановку, — для удобства поиска причины
`cached`	Кэшированные ошибки	`true` означает, что это кэшированный результат, распознавание не выполнялось
`badRequest`	Кэшированные ошибки	Параметры, попавшие в кэш
`limit`	`ERROR_THREADS_MAXIMUM`	Ваш текущий лимит параллельных задач

Правила выбора языка errorDescription описаны в разделе Запросы и ответы.