# Лимит параллельных задач и автоматическая приостановка

> Лимит параллельных задач YesCaptcha (ERROR_THREADS_MAXIMUM, баллы не списываются, в приостановку не засчитывается), автоматическая приостановка при большом числе ошибок (100 за минуту — на 5 минут, ERROR_IP_BLOCKED_5MIN) и кэш неверных параметров (cached).

Source: https://docs.yescaptcha.com/ru/api/rate-limits/ · 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/rate-limits/

Чтобы распознавание оставалось быстрым для всех пользователей, в YesCaptcha действуют три защитных правила: **число одновременно обрабатываемых задач** ограничено для каждого аккаунта (лимит параллельных задач); `clientKey`, который за короткое время дал **слишком много ошибок, приостанавливается** на несколько минут (автоматическая приостановка); **параметры, уже признанные неверными**, в течение некоторого времени сразу возвращают прежнюю ошибку (кэш неверных параметров). Во всех трёх случаях баллы не списываются.

## Лимит параллельных задач

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

-   Задача считается «в обработке» с момента вызова `createTask` до возврата ответа на этот вызов. Типы распознавания изображений возвращают результат прямо в `createTask`, поэтому **число параллельных задач ≈ число задач в секунду × время на одну задачу**. Например, при 0.5 секунды на задачу и 40 задачах в секунду получается примерно 20 параллельных задач.
-   Запросы одного аккаунта суммируются; каждый тип задачи считается отдельно.
-   Запросы сверх лимита сразу получают `ERROR_THREADS_MAXIMUM`, а в поле `limit` указан ваш текущий лимит. **Баллы не списываются, и такие запросы не засчитываются в автоматическую приостановку.**
-   Если серверы распознавания перегружены, у аккаунта, который занимает больше всего времени распознавания, лимит для этого типа задачи **временно уменьшается вдвое и автоматически восстанавливается через 10 минут**. Это только ограничение скорости, аккаунт не приостанавливается.
-   Если нужен более высокий лимит, [свяжитесь с поддержкой](https://docs.yescaptcha.com/ru/help/contact.md). Лимиты по умолчанию для каждого типа будут опубликованы на этой странице и в [журнале обновлений сервиса](https://docs.yescaptcha.com/ru/changelog.md) после того, как их утвердят.

```json
{
  "errorId": 1,
  "errorCode": "ERROR_THREADS_MAXIMUM",
  "errorDescription": "This account already has 30 tasks of this type in progress, which is the limit. Lower the concurrency and wait for pending requests to return before sending more; rejected requests are not charged and do not lead to a block.",
  "limit": 30
}
```

(Числа в примере приведены только для иллюстрации.)

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

1.  Ограничивайте в программе число запросов, которые одновременно ждут результата, например с помощью семафора (Semaphore) или пула потоков фиксированного размера, а не только число запросов в секунду.
2.  Получив `ERROR_THREADS_MAXIMUM`, дождитесь возврата уже отправленных запросов и только потом отправляйте новые либо подождите 1–2 секунды и повторите. Не повторяйте запрос сразу в цикле.
3.  Отправляйте пакеты задач равномерно, не запускайте десятки тысяч задач одновременно.

Пример на Python (asyncio):

```python
import asyncio
import os

import aiohttp

CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
LIMIT = 15  # below your concurrency limit
sem = asyncio.Semaphore(LIMIT)

async def solve(session, task):
    async with sem:  # at most LIMIT requests in progress at a time
        result = {}
        for attempt in range(5):
            async with session.post(
                "https://api.yescaptcha.com/createTask",
                json={"clientKey": CLIENT_KEY, "task": task},
            ) as resp:
                result = await resp.json()
            if result.get("errorCode") != "ERROR_THREADS_MAXIMUM":
                return result
            await asyncio.sleep(1 + attempt)  # over the limit: wait and retry
        return result
```

## Автоматическая приостановка

Если `clientKey` за короткое время отправляет много запросов с ошибками, создание задач для него автоматически приостанавливается:

| Условие срабатывания | Длительность приостановки |
| --- | --- |
| 100 перечисленных ниже ошибок в течение одной календарной минуты | 5 минут |
| Одна ошибка `ERROR_IMAGE_TYPE_NOT_SUPPORTED` | 30 минут |
| 1,000 попаданий в «кэш неверных параметров» в течение одной календарной минуты | 5 минут |

Ошибки, которые засчитываются в приостановку:

-   [`ERROR_REQUEST_FORMATS`](https://docs.yescaptcha.com/ru/api/errors.md#ERROR_REQUEST_FORMATS)
-   [`ERROR_TASK_ABSENT`](https://docs.yescaptcha.com/ru/api/errors.md#ERROR_TASK_ABSENT)
-   [`ERROR_TASK_NOT_SUPPORTED`](https://docs.yescaptcha.com/ru/api/errors.md#ERROR_TASK_NOT_SUPPORTED)
-   [`ERROR_KEY_DOES_NOT_EXIST`](https://docs.yescaptcha.com/ru/api/errors.md#ERROR_KEY_DOES_NOT_EXIST)
-   [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/ru/api/errors.md#ERROR_KEY_EXPIRED)
-   [`ERROR_TASKID_INVALID`](https://docs.yescaptcha.com/ru/api/errors.md#ERROR_TASKID_INVALID)
-   [`ERROR_SETTLEMENT_FAILED`](https://docs.yescaptcha.com/ru/api/errors.md#ERROR_SETTLEMENT_FAILED)
-   [`ERROR_HIGH_DEMAND_DOMAIN`](https://docs.yescaptcha.com/ru/api/errors.md#ERROR_HIGH_DEMAND_DOMAIN)
-   [`ERROR_ZERO_CAPTCHA_FILESIZE`](https://docs.yescaptcha.com/ru/api/errors.md#ERROR_ZERO_CAPTCHA_FILESIZE)
-   [`ERROR_TOO_BIG_CAPTCHA_FILESIZE`](https://docs.yescaptcha.com/ru/api/errors.md#ERROR_TOO_BIG_CAPTCHA_FILESIZE)
-   [`ERROR_IMAGE_TYPE_NOT_SUPPORTED`](https://docs.yescaptcha.com/ru/api/errors.md#ERROR_IMAGE_TYPE_NOT_SUPPORTED)
-   [`ERROR_ILLEGAL_IMAGE`](https://docs.yescaptcha.com/ru/api/errors.md#ERROR_ILLEGAL_IMAGE)

`ERROR_THREADS_MAXIMUM`, возвращаемая при превышении лимита параллельных задач аккаунта (с полем `limit`), не засчитывается; одноимённая ошибка, возвращаемая при перегрузке сервиса распознавания (без `limit`), засчитывается. Не засчитываются ошибки распознавания (`ERROR_CAPTCHA_UNSOLVABLE`), нехватка баланса (`ERROR_ZERO_BALANCE`), отсутствие обязательных полей (`ERROR_REQUIRED_FIELDS`), неподдерживаемый вопрос (`ERROR_UNKNOWN_QUESTION`) и подобные.

Во время приостановки:

-   Затрагиваются только `createTask` и `getBalance`, они возвращают `ERROR_IP_BLOCKED_5MIN`. `getTaskResult` работает как обычно: результаты задач, созданных до приостановки, можно получить.
-   В ответе есть `retryAfter` (сколько секунд осталось), `blockReason` (код ошибки, вызвавшей приостановку) и `blockDetail` (тип, URL и sitekey таких запросов); по ним можно исправить программу.
-   Дальнейшая отправка запросов не продлевает приостановку. Она снимается автоматически по истечении срока, обращаться в поддержку не нужно.
-   В Панели на [yescaptcha.com](https://yescaptcha.com/) на странице «Обзор» можно увидеть записи о приостановках за последние 24 часа.

```json
{
  "errorId": 1,
  "errorCode": "ERROR_IP_BLOCKED_5MIN",
  "errorDescription": "...",
  "retryAfter": 182,
  "blockReason": "ERROR_TASK_NOT_SUPPORTED"
}
```

## Кэш неверных параметров

Некоторые ошибки определяются параметрами запроса, поэтому при повторной отправке тех же параметров результат не изменится:

-   [`ERROR_RECAPTCHA_INVALID_SITEKEY`](https://docs.yescaptcha.com/ru/api/errors.md#ERROR_RECAPTCHA_INVALID_SITEKEY)
-   [`ERROR_RECAPTCHA_INVALID_DOMAIN`](https://docs.yescaptcha.com/ru/api/errors.md#ERROR_RECAPTCHA_INVALID_DOMAIN)
-   [`ERROR_INVALID_KEY_TYPE`](https://docs.yescaptcha.com/ru/api/errors.md#ERROR_INVALID_KEY_TYPE)
-   [`ERROR_DOMAIN_NOT_ALLOWED`](https://docs.yescaptcha.com/ru/api/errors.md#ERROR_DOMAIN_NOT_ALLOWED)

Эти ошибки не засчитываются в автоматическую приостановку, а кэшируются на уровне всего сервиса: после первого определения — на 2 минуты, а если в течение часа ошибка подтверждается повторно — на 10 минут. Пока кэш действует, такой же запрос (с тем же типом задачи и `websiteKey` или с тем же доменом сайта) сразу возвращает прежнюю ошибку, баллы не списываются, а в ответе есть `"cached": true`, `retryAfter` (сколько секунд осталось до конца кэширования) и `badRequest` (параметры, попавшие в кэш). Если исправить `websiteKey` или сменить тип задачи, изменения вступают в силу сразу.

## Чем отличаются лимит параллельных задач и автоматическая приостановка

|  | Лимит параллельных задач | Автоматическая приостановка |
| --- | --- | --- |
| Причина | Слишком много одновременно обрабатываемых задач | Слишком много запросов с ошибками за короткое время |
| Проявление | Отклоняются только запросы сверх лимита, `ERROR_THREADS_MAXIMUM` | Для этого `clientKey` приостанавливается создание задач, `ERROR_IP_BLOCKED_5MIN` |
| Восстановление | Новые запросы можно отправлять, как только предыдущие обработаны; вдвое уменьшенный лимит восстанавливается через 10 минут | Снимается автоматически по истечении срока |
| Списание баллов | Нет | Нет |