# Лимиты и ограничения

Какие лимиты баланса, недельных расходов, разрешенных моделей, параметров запроса и провайдеров проверяет хаб и какие ошибки возвращаются при их превышении.

При обработке запроса CoreInfra AI Hub последовательно проверяет формат и размер данных, список разрешенных моделей, недельные лимиты расходов и доступный остаток хаба, а после отправки запроса может вернуть ошибку от провайдера модели. Ниже описан каждый вид ограничений: кто им управляет, что именно считается, какой статус-код и формат ошибки возвращаются и как снять ограничение.

## Баланс хаба

* **Кто управляет:** владелец и администраторы хаба (пополняют баланс в разделе [«Оплата»](https://hub.coreinfra.ai/payments)).

* **Что учитывается:** доступный остаток хаба в рублях — текущий баланс за вычетом суммы активных резервов по всем незавершенным запросам (`Доступно = Баланс − Сумма активных резервов`, подробнее — в разделе [«Резервирование и списание»](https://coreinfra.ru/docs/models.md#reserve)). Запрос допускается к отправке, пока доступный остаток строго больше нуля (`Доступно > 0`). Запросы к моделям [подключенной подписки](https://coreinfra.ru/docs/subscriptions.md) (за исключением отдельно включенной проверки конфиденциальных данных с помощью модели) и вызовы подсчета токенов ([`count_tokens`](https://coreinfra.ru/docs/reference/anthropic/messages-count_tokens.md), [`input_tokens`](https://coreinfra.ru/docs/reference/openai/responses-input_tokens.md)) средства на балансе не резервируют; вызовы моделей других провайдеров через адреса подписок оплачиваются с баланса хаба.

* **Ошибка при нехватке средств:**

  * Ответ со статус-кодом `400` (`Content-Type: text/plain; charset=utf-8`).
  * Заголовки ответа: `x-coreinfra-status: payment-required` и `x-coreinfra-action-url` со ссылкой на страницу пополнения баланса этого хаба (`https://hub.coreinfra.ai/payments?hub_id=<UUID>`).
  * Текстовое тело предлагает пополнить баланс на CoreInfra AI Hub (для владельца и администраторов также выводятся текущий баланс, сумма в резерве и доступный остаток).

* **Как снять ограничение:** пополнить баланс через ЮКассу или активировать промокод в разделе [«Оплата»](https://hub.coreinfra.ai/payments) (см. [«Управление хабом»](https://coreinfra.ru/docs/hub.md#balance)), либо дождаться завершения выполняющихся запросов, которые удерживают резерв.

## Недельные лимиты расходов

Для каждого платного запроса проверяется условие:

```text
Расход за неделю + Активные резервы + Резерв нового запроса <= Действующий лимит
```

* **Кто управляет:**

  * лимитом **всего хаба** и лимитом **участника хаба** — владелец и администраторы хаба в разделе [«Настройки»](https://hub.coreinfra.ai/hub_management);
  * лимитом **отдельного ключа** — владелец этого ключа на [главной странице хаба](https://hub.coreinfra.ai).

* **Что учитывается:** сумма списанных расходов за текущую календарную неделю (с понедельника `00:00` до следующего понедельника `00:00` в часовом поясе хаба, по умолчанию МСК `UTC+3`) плюс сумма активных резервов незавершенных запросов этой области и расчетный резерв нового запроса. Для лимита участника суммируются расходы и резервы по всем его ключам в этом хабе; для лимита ключа учитывается вся цепочка перевыпусков этого ключа. Если поверх базового недельного лимита задан временный повышенный лимит на текущую неделю, до конца недели проверка сравнивает сумму с временным лимитом, а с понедельника автоматически возвращается к базовому. Проверки выполняются по порядку: сначала лимит хаба, затем лимит участника, затем лимит ключа.

* **Ошибка при превышении лимита:**

  * Ответ со статус-кодом `400` (`Content-Type: text/plain; charset=utf-8`) и заголовком `x-coreinfra-status: cost-limit-reached`.
  * В текстовом сообщении указано, какой именно лимит исчерпан — хаба, участника или ключа.

* **Как снять ограничение:** временно повысить лимит на текущую неделю или убрать базовый лимит в настройках хаба, участника или ключа (пошаговая инструкция — в разделе [«Командная работа и аналитика»](https://coreinfra.ru/docs/team-analytics.md#limits)), либо дождаться начала следующей недели в понедельник в `00:00`.

## Разрешенные модели

* **Кто управляет:**

  * списком моделей **хаба** и **участника** — владелец и администраторы хаба в разделе [«Настройки»](https://hub.coreinfra.ai/hub_management);
  * списком моделей **ключа** — владелец ключа на [главной странице хаба](https://hub.coreinfra.ai).

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

* **Ошибка при блокировке модели:**

  * Ответ со статус-кодом `400` (`Content-Type: text/plain; charset=utf-8`), в тексте которого указана заблокированная модель и уровень ограничения (настройки хаба, участника или ключа).
  * Если запрошенной модели нет в каталоге хаба, возвращается ответ со статус-кодом `400` (`text/plain`) о том, что модель не поддерживается.

* **Как снять ограничение:** выбрать модель из разрешенного списка либо добавить нужную модель (или очистить фильтр кнопкой «Разрешить все модели») в настройках соответствующего уровня (см. [«Командная работа и аналитика»](https://coreinfra.ru/docs/team-analytics.md#limits)).

## Ограничения хаба на один запрос

Эти ограничения задает хаб. Они проверяются до резервирования средств и обращения к провайдеру модели:

* **Размер тела и заголовков запроса:**

  * Максимальный размер тела HTTP-запроса — **100 МиБ** (`104 857 600` байт); для сжатых POST-запросов этот предел действует как на сжатое, так и на распакованное тело. На [`/fal/api`](https://coreinfra.ru/docs/use/fal.md) максимальный размер тела запроса составляет **64 МиБ**. При превышении возвращается ошибка со статус-кодом `413`.
  * Сжатие тела запроса (`Content-Encoding`) поддерживает `gzip`, `deflate`, `br` и `zstd` (размер окна `zstd` — до **8 МиБ**). При другом алгоритме сжатия возвращается ошибка со статус-кодом `415` и заголовком `Accept-Encoding: gzip, deflate, br, zstd`.
  * Максимальный размер стартовой строки и заголовков HTTP/1-запроса — **64 КиБ** (`65 536` байт), время ожидания чтения заголовков — **30 секунд**.

* **Токены и число элементов в запросе эмбеддингов ([`POST /openai/api/v1/embeddings`](https://coreinfra.ru/docs/reference/openai/embeddings.md)):**
  * Не более **300 000 токенов** и не более **2048 элементов** в массиве `input` в одном запросе. При превышении возвращается ошибка со статус-кодом `400` в формате ошибок OpenAI (`code: "max_tokens_per_request"` для лимита токенов).

* **Формат изображений, документов и файлов:**

  * Все входные изображения и бинарные файлы передаются непосредственно в запросе в кодировке base64 (`data:image/...;base64,...`, блок `source` с `type: "base64"` в Anthropic Messages, поле `data` в Google Interactions или части `multipart/form-data`); для блоков `document` в Anthropic Messages также допускаются встроенный текст (`text`) и вложенный `content`.
  * Ссылки на внешние ресурсы (`http(s)`) и идентификаторы файлов в хранилище провайдера (`file_id`, `files/...`) отклоняются со статус-кодом `400` в формате ошибок вызванного протокола (на [`/fal/api`](https://coreinfra.ru/docs/use/fal.md) — со статус-кодом `422`).
  * В [моделях принятия решений](https://coreinfra.ru/docs/decisions.md) при конвертации изображений между OpenAI Decisions и TypeSafe System One принимаются только PNG и JPEG в кодировке base64, а размер преобразованного запроса ограничен **32 МиБ** (при превышении возвращается ошибка со статус-кодом `400`).

Ограничения отдельных протоколов и параметров (неподдерживаемые фоновые режимы, встроенные инструменты и др.) приведены на страницах соответствующих API: [OpenAI](https://coreinfra.ru/docs/use/openai.md#limits), [Anthropic](https://coreinfra.ru/docs/use/anthropic.md#limits), [Google](https://coreinfra.ru/docs/use/google.md#limits), [xAI](https://coreinfra.ru/docs/use/xai.md#limits), [OpenRouter](https://coreinfra.ru/docs/use/openrouter.md#limits), [TypeSafe](https://coreinfra.ru/docs/use/typesafe.md#limits) и [fal](https://coreinfra.ru/docs/use/fal.md#limits).

## Лимиты и ошибки провайдера

* **Кто управляет:** провайдер модели.

* **Что учитывается:** частота запросов и токенов на стороне провайдера (rate limits), максимальное контекстное окно модели (`context_window` и `max_output_tokens`), правила безопасности контента и доступность инфраструктуры провайдера.

* **Ошибки со стороны провайдера:**

  * **Ограничение частоты запросов (`429`):** возвращается ошибка со статус-кодом `429` в формате ошибок вызванного протокола и заголовками `retry-after` / `retry-after-ms`.
  * **Временная недоступность провайдера (`503`):** возвращается ошибка со статус-кодом `503`.
  * **Отклонение запроса по правилам контента или прав (`403`):** возвращается ошибка со статус-кодом `403`.
  * **Превышение контекстного окна или ошибка параметров модели (`400`):** возвращается ошибка со статус-кодом `400`, а резерв освобождается без списания.

* **Как снять ограничение:** при статус-коде `429` повторите запрос после интервала из `retry-after` / `retry-after-ms`, при `503` повторите запрос позже или переключитесь на другую модель, при `400` или `403` сократите длину диалога или скорректируйте параметры запроса.

## Как определить причину ошибки

| Статус-код и признак в ответе                                                                    | Какое ограничение сработало                                                | Где настраивается / что делать                                                                                                                                                                                                                |
| ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`, заголовок `x-coreinfra-status: payment-required`                                          | Исчерпан доступный остаток хаба (`Доступно <= 0`)                          | Пополнить баланс или ввести промокод в разделе [«Оплата»](https://hub.coreinfra.ai/payments) (см. [«Управление хабом»](https://coreinfra.ru/docs/hub.md#balance))                                                                             |
| `400`, заголовок `x-coreinfra-status: cost-limit-reached`                                        | Исчерпан недельный лимит расходов хаба, участника или ключа                | Проверить лимиты в разделе [«Настройки»](https://hub.coreinfra.ai/hub_management) или у ключа на [главной странице хаба](https://hub.coreinfra.ai) (см. [«Командная работа и аналитика»](https://coreinfra.ru/docs/team-analytics.md#limits)) |
| `400` (`text/plain`), модель заблокирована настройками                                           | Белый список моделей хаба, участника или ключа                             | Добавить модель в разрешенные в разделе [«Настройки»](https://hub.coreinfra.ai/hub_management) или в настройках ключа на [главной странице хаба](https://hub.coreinfra.ai)                                                                    |
| `400` (`text/plain`), модель не поддерживается                                                   | Модель отсутствует в каталоге хаба                                         | Проверить идентификатор модели в [«Каталоге моделей»](https://coreinfra.ru/docs/catalog.md)                                                                                                                                                   |
| `400` или `401`, ошибка проверки ключа                                                           | Не передан, поврежден или отозван ключ `sk-ci2-...`                        | Проверить заголовок авторизации и активные ключи на [главной странице хаба](https://hub.coreinfra.ai)                                                                                                                                         |
| `400`, ошибка вложения (ссылка на внешний ресурс или `file_id`)                                  | Передана ссылка на внешний ресурс или `file_id` вместо base64              | Передать изображение или файл в кодировке base64 (`data:image/...;base64,...`)                                                                                                                                                                |
| `422` на [`/fal/api`](https://coreinfra.ru/docs/reference/fal/submit.md)                         | Некорректные `duration`, `resolution` или ссылка в `image_url`             | Указать `duration` от `5` до `20`, поддерживаемое `resolution` и передать кадры через `fal_client.encode_file()`                                                                                                                              |
| `400` на [`/openai/api/v1/embeddings`](https://coreinfra.ru/docs/reference/openai/embeddings.md) | Превышен лимит 300 000 токенов или 2048 элементов `input`                  | Разбить входной массив на несколько запросов                                                                                                                                                                                                  |
| `413 Payload Too Large`                                                                          | Тело запроса превышает допустимый размер (100 МиБ; на `/fal/api` — 64 МиБ) | Уменьшить размер вложений или истории сообщений в запросе                                                                                                                                                                                     |
| `415 Unsupported Media Type`                                                                     | Неподдерживаемый `Content-Encoding`                                        | Сжимать запрос с помощью `gzip`, `deflate`, `br` или `zstd` либо отправлять без сжатия                                                                                                                                                        |
| `429 Too Many Requests`                                                                          | Лимит частоты запросов у провайдера модели                                 | Повторить запрос с учетом заголовков `retry-after` / `retry-after-ms`                                                                                                                                                                         |
| `503 Service Unavailable`                                                                        | Временная недоступность провайдера модели                                  | Повторить запрос позже или выбрать другую модель                                                                                                                                                                                              |
| `403 Forbidden`                                                                                  | Запрос отклонен провайдером по содержимому или правилам модели             | Изменить текст запроса или выбрать другую модель                                                                                                                                                                                              |

## Ограничения WebSocket

После установления WebSocket ошибки передаются событиями `error`. Проверки баланса, расходов и разрешенных моделей выполняются для каждого оплачиваемого ответа в сессии.

Ограничения размера и времени задает сервер хаба:

* Размер одного сообщения и кадра ограничен тем же значением, что и тело HTTP-запроса, — 100 МиБ. Превышение завершает соединение; уменьшите сообщение.
* Соединение OpenAI Responses или Realtime живет не более часа (по истечении срока приходит событие `error` с кодом `websocket_connection_limit_reached` в Responses или `session_expired` в Realtime). Для продолжения откройте новое соединение.
* В Realtime поле `metadata` у `response.create` может содержать не более 15 пар ключ–значение (при превышении приходит событие `error` с кодом `metadata_full`).

При неподдерживаемом или неудавшемся WebSocket Upgrade возвращается ответ со статус-кодом `426`. Требования к подключению приведены в справочниках [OpenAI Responses](https://coreinfra.ru/docs/reference/openai/responses.md) и [Realtime](https://coreinfra.ru/docs/reference/openai/realtime.md).
