# Ключи и лимиты

Запрос проходит, когда ключ активен, денег хватает на резерв и не исчерпан ни один лимит. Ниже — что ограничивает запросы и что в этом случае получит твой код.

## Ключ

Ключи компании выпускают владелец и администратор, участник — свои личные ключи, если владелец или администратор это разрешил в разделе «Команда». У бухгалтера ключей нет.

Ключ целиком показывается один раз, при выпуске. Konductor хранит только его хэш и первые 12 символов, поэтому вернуть ключ не сможет: потерял — выпусти новый, а старый отзови.

Из кода ключ выпускает `POST /v1/admin/keys` с ключом компании в `Authorization: Bearer`. В теле — `name`, по желанию `limitKop` (копейки, целое число больше нуля) вместе с `limitWindow` (`day`, `week` или `month`), `expiresAt` и `allowedModels`. Ключ без лимита выпускай без `limitKop` и `limitWindow`: `limitWindow: none` не принимается. Секрет придёт один раз в поле `secret`. Отозвать ключ — `POST /v1/admin/keys/{id}/revoke`. Поля — в [OpenAPI](/konductor/openapi.json).

Ключ идёт в заголовке `Authorization: Bearer $KONDUCTOR_KEY`. Для `/v1/messages` и `/v1/key` подойдёт и заголовок `x-api-key`.

| Статус | Что с запросами |
|---|---|
| Активен | Проходят, если хватает денег и лимитов |
| На паузе | 403 `key_paused`; в тексте ошибки — кто поставил паузу: Konductor из-за нехватки денег на балансе или владелец с администратором в панели. Снять паузу можно, когда баланс компании больше нуля |
| Заблокирован | 403 `key_blocked` |
| Компания заблокирована или закрыта | 403 `company_blocked` у всех ключей компании: напиши в поддержку |
| Отозван | 401 `invalid_api_key`: ключ больше не принимается |
| Срок истёк | 401 `key_expired`. Срок задаёт владелец или администратор при выпуске ключа компании; без срока ключ бессрочный |

Новый статус начинает действовать не позже чем через 5 секунд.

Если запрос по факту стоил больше, чем осталось на балансе, разницу Konductor списывает за свой счёт: баланс становится 0, а ключ встаёт на паузу до пополнения. Паузу в панели владелец или администратор ставят и снимают сами, баланс тут ни при чём.

## Лимиты

| Ограничение | Период | Что при упоре | Где поднять |
|---|---|---|---|
| Баланс компании | — | 402 `insufficient_balance` | Пополни баланс |
| Лимит ключа в рублях | день, неделя или месяц; без лимита период не нужен | 402 `key_limit_exceeded` | В карточке ключа |
| Месячный потолок участника — на все его личные ключи | месяц | 402 `member_limit_exceeded` | Попроси владельца или администратора компании |
| Лимит компании в рублях | месяц или без периода | 402 `company_limit_exceeded` | Напиши в поддержку |
| Запросов в минуту — у ключа и у компании, если оператор задал | минута | 429 `rate_limit_exceeded` | Подожди столько секунд, сколько в `Retry-After`; поднять лимит — напиши в поддержку |

Периоды считаются по Москве: день — с 00:00, неделя — с понедельника 00:00, месяц — с 1-го числа. Когда период начнётся заново, написано в поле `reset_at` ответа.

Денежные лимиты проверяются по порядку: ключ, участник, компания. Ответ называет первый исчерпанный в поле `limit_scope`. Потолок участника 0 — запросы его личными ключами не проходят.

По умолчанию частота не ограничена, и `rpm_limit` в `/v1/key` равен `null`. Лимит у ключа и у компании задаёт оператор по запросу в поддержку.

Запросы в минуту считаются вместе для `/v1/chat/completions`, `/v1/messages`, `/v1/responses` и `/v1/models`, включая отклонённые с 400 и 402. Минута отсчитывается с её начала, поэтому на стыке двух минут может пройти вдвое больше запросов, чем `rpm_limit`.

## Как считается расход

Перед запросом Konductor резервирует деньги: оценка входа по цене входа плюс `max_tokens` по цене выхода. После ответа списывается фактическая цена, остаток резерва возвращается.

Расход периода — списания за этот период плюс резервы запросов, которые ещё идут, и резервы запросов с неизвестным исходом. Поэтому лимит может закончиться раньше, чем показывают списания: часть его держат запросы в обработке.

## Как узнать остаток

Запрос к `/v1/key` ничего не списывает и не расходует лимит запросов в минуту:

```bash
curl https://llm.kodzavod.ru/v1/key \
  -H "Authorization: Bearer $KONDUCTOR_KEY"
```

В ответе — статус ключа, его лимит в рублях и период (`limit_kop`, `limit_window`), расход и остаток (`spent_kop`, `in_flight_kop`, `limit_remaining_kop`), начало нового периода (`reset_at`) и лимит запросов в минуту (`rpm_limit`). В поле `member` — месячный потолок участника (только у личного ключа). Поле `company` по умолчанию `null`: баланс и лимит компании ключу не показываются. Суммы — копейки, строкой.

Тела ответов с отказом — в разделе [«Ошибки»](/konductor/docs/errors).