Лимиты

Два независимых типа ограничений. Технические лимиты применяются автоматически ко всем ключам — они защищают сервис от перегрузки. Лимиты расходов вы настраиваете сами для каждого ключа — это удобно, когда ключ уходит в продакшн или попадает в чужие руки.

Технические лимиты

ЛимитЗначениеПрименяется
Запросов в минуту 500 RPM На каждый API ключ отдельно
Размер аудиофайла до 25 МБ Endpoint /v1/audio/transcriptions

Каждый ответ роутера содержит заголовки с текущим состоянием лимита запросов:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 495
X-RateLimit-Reset: 45

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

У каждого API ключа есть до четырёх независимых ограничений по расходу в рублях. Любой из них можно оставить пустым — тогда лимит не применяется, но текущий расход в этом окне всё равно виден в настройках ключа.

Окно Поведение Когда исчерпан
Общий лимит Жёсткий потолок за всё время существования ключа HTTP 402 · spending_limit_exceeded
Ключ остаётся заблокированным, пока вы не повысите или не уберёте лимит.
Лимит в час Скользящее окно — сумма расходов за последние 60 минут HTTP 429 · spending_limit_exceeded
Окно сдвигается автоматически — лимит освобождается по мере того, как старые запросы выходят за его границу.
Лимит в день Скользящее окно — последние 24 часа
Лимит в неделю Скользящее окно — последние 7 дней

Все четыре лимита применяются до отправки запроса в провайдера. Если хотя бы один из них исчерпан, запрос блокируется с соответствующим кодом — провайдеру оплата не уходит, расходы не растут.

Формат ответа

При исчерпании любого скользящего лимита роутер возвращает HTTP 429 с указанием окна:

{
  "error": {
    "message": "API key hour spending limit reached (11.00 ₽ / 10.00 ₽). Try again later or raise the limit.",
    "type": "spending_limit_exceeded",
    "window": "hour"
  }
}

Поле window принимает значения hour, day или week. Если же исчерпан общий лимит — код 402, поле window отсутствует: 

{
  "error": {
    "message": "API key spending limit reached",
    "type": "spending_limit_exceeded"
  }
}

Где настраивать

На странице API ключи кликните по ячейке «Лимит» нужного ключа. В диалоге показаны все четыре окна — для каждого виден текущий расход, и когда вы устанавливаете ограничение, прямо в диалоге появляется индикатор насыщения (зелёный → жёлтый → красный).

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

Практические сценарии

  • Продакшн-ключ — задайте недельный лимит чуть выше ожидаемой нагрузки. Если кто-то случайно зациклит запросы, потери ограничены неделей.
  • Тестовый ключ для CI — поставьте лимит в час, равный одному прогону тестов × запас 2×. Сломанный тест не съест бюджет за ночь.
  • Демо-ключ для интеграции — общий лимит с небольшой суммой. Когда деньги заканчиваются, ключ корректно отказывает с 402, и можно решить, повышать лимит или закрыть демо.
  • Сервис с переменной нагрузкой — комбинируйте: жёсткий общий потолок + мягкий часовой как сигнал «что-то идёт не так», который можно отлавливать в логах по window: hour.

Лимиты расходов независимы от баланса аккаунта. Если у пользователя есть деньги, но лимит ключа достигнут — запрос всё равно блокируется. И наоборот: если лимит ключа высокий, но баланс кончился, ответ будет 402 с типом billing_error.