# Несколько clientKey: лимиты расходов, белый список IP и срок действия

> В одном аккаунте YesCaptcha может быть до 20 clientKey, все они списывают баллы с одного баланса. Для каждого можно отдельно задать лимит расходов (в день, неделю, месяц или единоразовый, сброс по пекинскому времени), белый список IP и срок действия, изменения вступают в силу за несколько секунд.

Source: https://docs.yescaptcha.com/ru/account/client-keys/ · Last verified: 2026-10-29

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

В одном аккаунте YesCaptcha может быть до 20 `clientKey` (включая исходный). Они управляются на странице «Ключи и безопасность» в Панели [yescaptcha.com](https://yescaptcha.com/security). Каждый `clientKey` может создавать задачи и запрашивать баланс, и все они списывают баллы с одного баланса аккаунта. Для каждого можно отдельно задать лимит расходов, белый список IP и срок действия, изменения вступают в силу за несколько секунд.

Типичные сценарии: разные ключи для тестового и рабочего окружения или для разных проектов; ключи для ваших клиентов или партнёров, у каждого свой лимит; если один `clientKey` утёк, вы удаляете только его, остальные программы не затрагиваются.

## Основной и дополнительные ключи

|  | Основной ключ | Дополнительный ключ |
| --- | --- | --- |
| Что это | Исходный `clientKey`, по одному на аккаунт | Любой ключ, созданный помимо основного, до 19 |
| Лимит, белый список IP, срок действия | Можно задать | Можно задать |
| Сброс | Можно: старый сразу перестаёт работать, баланс переходит к новому | Нельзя, удалите его и создайте новый |
| Удаление | Нельзя | Можно: перестаёт работать за несколько секунд, восстановить нельзя |

-   Формат у всех одинаковый: первые 40 символов — секретная часть, дальше ваш ID пользователя.
-   Сброс основного ключа не влияет на дополнительные.
-   С каким бы `clientKey` вы ни создавали задачи и ни запрашивали баланс, API и ответы одинаковы, добавляются только проверки лимита, белого списка IP и срока действия.

## Создание clientKey

1.  Войдите на [yescaptcha.com](https://yescaptcha.com/) и откройте страницу «Ключи и безопасность» ([yescaptcha.com/security](https://yescaptcha.com/security)).
2.  В разделе «Все ключи» нажмите «Новый доп. ключ». Название (до 40 символов), лимит, белый список IP и срок действия можно не заполнять, позже их можно изменить.
3.  По запросу ещё раз подтвердите личность. Подтверждение нужно при создании, изменении и удалении.
4.  После создания скопируйте полный `clientKey` и пропишите его в программе. Позже его можно снова посмотреть в списке, нажав на значок глаза.

> **Заметка:** Создание, изменение и удаление вступают в силу за несколько секунд. Если вызвать API сразу после создания, может прийти `ERROR_KEY_DOES_NOT_EXIST`, подождите несколько секунд и повторите. В течение нескольких секунд после удаления ключа или ужесточения настроек запросы, которые уже отправлены, могут обрабатываться по прежним настройкам.

## Лимит расходов

Лимит ограничивает, сколько баллов `clientKey` может потратить за один период (1,000 баллов = ¥1). Его можно задать от 1 до 10,000,000,000 баллов. Периодов четыре, сброс происходит по пекинскому времени (UTC+8):

| Период | Когда сбрасывается |
| --- | --- |
| День | Каждый день в 00:00 |
| Неделя | Каждый понедельник в 00:00 |
| Месяц | 1-го числа каждого месяца в 00:00 |
| Единоразовый | Не сбрасывается. После исчерпания этот `clientKey` больше не может создавать задачи, чтобы продолжить, увеличьте лимит |

-   Считаются фактически списанные баллы: баллы, возвращённые за нераспознанные задачи или за таймаут, возвращаются и в лимит.
-   Если остатка лимита в текущем периоде не хватает на списание за задачу, `createTask` возвращает [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/ru/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED). Баллы не списываются, ошибка не учитывается в [автоматической приостановке](https://docs.yescaptcha.com/ru/api/rate-limits.md).
-   В списке в Панели видно, сколько каждый `clientKey` израсходовал в текущем периоде и когда лимит будет сброшен в следующий раз.
-   Лимит — это не отдельный баланс: все `clientKey` списывают баллы с одного баланса аккаунта, и когда на балансе аккаунта не хватает баллов, как обычно возвращается `ERROR_ZERO_BALANCE`.

Если вызвать [`getBalance`](https://docs.yescaptcha.com/ru/api/get-balance.md) с `clientKey`, для которого задан лимит, то `balance` — это меньшее из значений: баланс аккаунта и остаток лимита в текущем периоде. Дополнительно приходит поле `keyQuotaRemaining` (остаток лимита, в баллах). Для `clientKey` без лимита это поле не возвращается, ответ такой же, как раньше.

```json
{
  "errorId": 0,
  "balance": 20000,
  "softBalance": 0,
  "inviteBalance": 0,
  "inviteBy": 0,
  "keyQuotaRemaining": 20000
}
```

## Белый список IP

`clientKey` с белым списком IP работает только для запросов с адресов из этого списка. Пустой список означает отсутствие ограничений.

-   Укажите **публичный IP машины, которая вызывает API YesCaptcha** (исходящий IP), а не прокси из параметров задачи. Если API вызывают несколько машин, добавьте публичный IP каждой.
-   По одному адресу IPv4 или IPv6 или диапазону CIDR в строке, не более 50 записей. Одиночный адрес разрешает только этот IP.
-   Диапазон нужно записывать адресом сети: `203.0.113.0/24` подойдёт, `203.0.113.5/24` нет (биты хоста не равны нулю).

```text
203.0.113.10
198.51.100.0/24
2001:db8::/32
```

-   Если IP запроса нет в списке, `createTask` и `getBalance` возвращают [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/ru/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED). Баллы не списываются, ошибка не учитывается в автоматической приостановке.
-   Если ваш исходящий IP меняется (домашний интернет, облачные функции, ротация исходящих адресов), не задавайте список или разрешите весь диапазон.

## Срок действия

-   Для любого `clientKey`, включая основной, можно задать срок действия не более чем на десять лет вперёд. Позже его можно в любой момент изменить или убрать.
-   После истечения срока `createTask` и `getBalance` с этим ключом возвращают [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/ru/api/errors.md#ERROR_KEY_EXPIRED), баллы не списываются. Уже созданные задачи по-прежнему можно получить через `getTaskResult`.
-   Если `clientKey` долго не использовался, система ради безопасности аккаунта задаёт ему срок действия и перед истечением присылает напоминание на почту. Такой срок изменить нельзя: заново сгенерируйте основной ключ (баланс автоматически перейдёт к новому) или создайте новый `clientKey`, затем обновите его в программе.

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

-   **Баланс**: все `clientKey` списывают баллы с одного баланса аккаунта. Пополнение, бонус за VIP, реферальное вознаграждение и доля разработчика относятся к аккаунту, независимо от того, каким `clientKey` вы пользуетесь.
-   **Лимит параллельных задач**: считается на аккаунт, все `clientKey` вместе подчиняются одному пределу, см. [Лимит параллельных задач и автоматическая приостановка](https://docs.yescaptcha.com/ru/api/rate-limits.md).
-   **Автоматическая приостановка**: считается отдельно для каждого `clientKey`. Если один `clientKey` приостановлен из-за слишком большого числа ошибок, на остальные это не влияет.

## Связанные коды ошибок

| Код ошибки | Когда возвращается |
| --- | --- |
| [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/ru/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED) | Остатка лимита в текущем периоде не хватает на эту задачу (`createTask`) |
| [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/ru/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED) | IP запроса нет в белом списке IP этого `clientKey` (`createTask`, `getBalance`) |
| [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/ru/api/errors.md#ERROR_KEY_EXPIRED) | Срок действия `clientKey` истёк (`createTask`, `getBalance`) |

Ни в одном из этих случаев баллы не списываются. Что делать, см. в разделе [Коды ошибок](https://docs.yescaptcha.com/ru/api/errors.md).