# Коды ошибок

> Все коды ошибок YesCaptcha API, их значение и что делать: формат запроса, аккаунт и баланс, параллельные задачи и приостановка, результат задачи, параметры сайта, изображения, прокси, сервер. За запросы, вернувшие ошибку, баллы не списываются.

Source: https://docs.yescaptcha.com/ru/api/errors/ · Last verified: 2026-10-15

> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/errors/

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

> **Совет:** В коде ориентируйтесь на `errorCode`, а не на текст `errorDescription`: текст описания может измениться.

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

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

1.  **Ошибки параметров** (формат запроса, ClientKey, тип задачи, параметры сайта, изображения) не исчезнут при повторной отправке — сначала исправьте запрос.
2.  **Неудачное распознавание и тайм-аут** (`ERROR_CAPTCHA_UNSOLVABLE`, `ERROR_TASK_TIMEOUT`) можно повторить, создав задачу заново.
3.  После ошибки **прекратите опрос** (polling) этого `taskId` и не отправляйте тот же запрос повторно с высокой частотой.
4.  Ошибки с пометкой «Учитывается в приостановке»: если для одного `clientKey` набирается 100 таких ошибок за минуту, создание задач приостанавливается на 5 минут. Ошибки с пометкой «Кэшируется» в этот счётчик не входят, но пока действует кэш, одинаковые запросы сразу получают прежнюю ошибку. Подробнее — в разделе [Лимит параллельных задач и автоматическая приостановка](https://docs.yescaptcha.com/ru/api/rate-limits.md).

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

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

| Код ошибки | Значение | Что делать |
| --- | --- | --- |
| `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` описаны в разделе [Запросы и ответы](https://docs.yescaptcha.com/ru/api/overview.md).