Лимиты

Баланс организации, ошибка 402, ограничение запросов, обработка 429 и сбои во время потока.

В AI Gateway доступ к API ограничивают два независимых условия: положительный баланс организации и частота запросов конкретного ключа. Если средств недостаточно, запрос отклоняется с HTTP 402 и кодом insufficient_balance; если ключ превышает допустимую частоту, шлюз возвращает HTTP 429. Эти ошибки требуют разной реакции приложения.

Новый ключ по умолчанию получает лимит 120 запросов в минуту. Пользователь не может изменить RPM в кабинете: если текущего значения недостаточно, обратитесь в поддержку, чтобы администратор оценил сценарий и при необходимости изменил лимит.

Как проверить лимиты

Проверяйте не одно число, а три связанных показателя:

В разделе API-ключи проверьте статус нужного ключа, последнее использование и расход за 30 дней. Там же журнал ключа показывает изменения лимита, если их выполнял администратор.
На главной странице кабинета проверьте текущий баланс, прогноз и расход за месяц. Пополнить баланс или создать счёт можно в разделе Биллинг.
Для диагностики нагрузки откройте Использование с отдельными событиями и Аналитику с разбивкой по ключам и моделям.

Для нового ключа ориентир — 120 RPM. Если поддержка ранее меняла значение, не пытайтесь определить точный лимит серией тестовых запросов: такая проверка сама создаёт нагрузку. Сверьте журнал ключа или уточните действующее значение в поддержке.

Баланс и RPM не заменяют друг друга. Положительный баланс не снимает ограничение частоты, а свободный RPM не позволяет выполнять запросы при остановке ключа из-за баланса. Стоимость моделей смотрите на странице цен.

Ограничение по балансу

Расходы API списываются с баланса организации. Когда баланс становится равен нулю или уходит ниже нуля, активные ключи автоматически приостанавливаются. Проверка допуска для такого ключа возвращает:

HTTP 402
code: insufficient_balance

Это не временная перегрузка. Повторять тот же запрос с нарастающей задержкой бессмысленно, пока баланс не станет положительным.

Как обрабатывать 402

Остановите автоматические повторы и новые фоновые задания для этой организации.
Запишите HTTP-статус, код ошибки, время, маршрут и безопасный префикс ключа. Полный ключ в журнал не помещайте.
Покажите оператору или пользователю понятное действие: проверить баланс и перейти в Биллинг.
После подтверждённого пополнения выполните один контрольный запрос. Если 402 сохраняется, проверьте статус ключа и обратитесь в поддержку.

После положительного пополнения периодическая системная проверка автоматически возобновляет только ключи, которые были приостановлены из-за баланса. Это может произойти не в ту же миллисекунду, что и платёж, поэтому дождитесь обновления баланса и используйте ограниченную проверку готовности.

Ручное отключение — другое состояние. Ключ, который пользователь отключил сам, не должен автоматически включаться после пополнения. Сначала убедитесь, что ключ действительно был остановлен из-за баланса, а не отключён вручную.

Ограничение частоты запросов

RPM — число запросов конкретного API-ключа за минутное окно. Для нового ключа AI Gateway применяет 120 запросов в минуту. Одновременный всплеск из нескольких процессов может исчерпать этот лимит быстрее, чем равномерная нагрузка.

При превышении лимита шлюз возвращает HTTP 429. Не рассчитывайте на заголовок с остатком запросов или на точное значение Retry-After: клиент должен корректно работать и без них.

Как обрабатывать 429

Сначала уменьшите локальную конкуренцию: поставьте запросы в очередь и ограничьте число одновременных обращений одним регулятором на ключ. Затем повторяйте только те операции, для которых повтор безопасен.

Используйте конечное число попыток, нарастающую задержку и случайный разброс. Например, логика может выглядеть так:

const maxAttempts = 4;

for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
  const response = await callSmartaipack();

  if (response.status !== 429) {
    return response;
  }

  if (attempt === maxAttempts - 1) {
    throw new Error("rate_limit_exceeded");
  }

  const baseDelayMs = 500 * 2 ** attempt;
  const jitterMs = Math.floor(Math.random() * 250);
  await wait(baseDelayMs + jitterMs);
}

Функции callSmartaipack() и wait() здесь условные: реализуйте их своим HTTP-клиентом. Не запускайте бесконечные повторы и не дублируйте запрос, если не уверены, что повтор безопасен. После исчерпания попыток верните управляемую ошибку вызывающей системе или оставьте задачу в очереди для более позднего запуска.

Если 429 возникает при нормальной постоянной нагрузке, соберите фактические данные в Аналитике и обратитесь в поддержку. Пользовательский интерфейс не изменяет RPM, но администратор или поддержка может скорректировать его под подтверждённый сценарий.

Ограничение во время потока

Для потокового ответа важно различать отказ до начала передачи и обрыв уже открытого соединения. Лимит RPM конкретного ключа обычно проверяется до начала запроса. Если шлюз вернул 429 до открытия успешного потока, применяйте ограниченную стратегию повторов из предыдущего раздела.

После начала потока HTTP-статус уже отправлен. Обрыв соединения в этот момент сам по себе не доказывает превышение RPM: причиной может быть сеть, тайм-аут, отмена клиентом или ошибка поставщика. Не классифицируйте такой обрыв как 429 без явного события или кода ошибки.

Для уже начавшегося потока сохраняйте полученные части отдельно от признака успешного завершения. При обрыве:

отметьте ответ как неполный;
сохраните доступный код или событие ошибки;
не склеивайте частичный ответ с результатом автоматического повтора;
повторяйте запрос только при безопасной семантике и с ограничением числа попыток;
сверяйте факт запроса и расход в разделе Использование.

Подробная работа с SSE, завершением и отменой разобрана в статье «Потоковые ответы AI Gateway». Правила безопасного хранения ключа и диагностики авторизации — в материале «Авторизация в API».