Лимиты и квоты

Лимиты по умолчанию

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

• Окно скользящее. Оно не обнуляется в начале минуты: освобождается по мере того, как стареют предыдущие запросы. Ровный поток проходит там, где залповый упирается в лимит.
• Токены считаются авансом. На входе резервируется prompt_tokens плюс max_tokens. После ответа резерв пересчитывается по фактическому usage — завышенный max_tokens съедает окно зря.
• Лимиты растут вместе с историей. Аккаунтам со стабильным трафиком и оплаченным расходом пороги поднимаются по запросу в поддержку — обычно в течение рабочего дня.

Заголовки ответа

Каждый ответ несёт состояние обоих окон. Читайте их в клиенте — это дешевле, чем ловить 429 и разбирать бэкофф.

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_td_8f31c0a94e2b
X-RateLimit-Limit-Requests: 60
X-RateLimit-Remaining-Requests: 57
X-RateLimit-Reset-Requests: 41s
X-RateLimit-Limit-Tokens: 150000
X-RateLimit-Remaining-Tokens: 132480
X-RateLimit-Reset-Tokens: 41s

Значения Reset приходят в секундах с суффиксом s. Быстрый способ посмотреть текущее состояние — запросить каталог моделей и распечатать заголовки: этот запрос не тратит токены.

curl -sS -D - -o /dev/null https://api.tokendock.cloud/v1/models \
  -H "Authorization: Bearer $TOKENDOCK_API_KEY" \
  | grep -i "^x-ratelimit"

Практическое правило: когда X-RateLimit-Remaining-Tokens опускается ниже десятой части от лимита, притормозите отправку сами. Это ровнее, чем упереться в отказ и разбирать очередь повторов.

429 и что делать

Ответ 429 с типом rate_limit_error означает одно: окно закрыто. Запрос не выполнен и не тарифицирован, повторить его можно без последствий.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-Request-Id: req_td_2b70ce41ad99
X-RateLimit-Limit-Requests: 60
X-RateLimit-Remaining-Requests: 0
X-RateLimit-Reset-Requests: 12s
Retry-After: 12

• Сначала Retry-After. Заголовок говорит, через сколько секунд открывается окно. Собственная формула нужна только тогда, когда заголовка нет.
• Экспоненциальный бэкофф с джиттером. 1 с, 2 с, 4 с, 8 с плюс случайная добавка. Без джиттера параллельные воркеры возвращаются одновременно и получают тот же отказ.
• Очередь вместо ретрая в лоб. Для фоновых задач — очередь с ограничителем скорости на стороне приложения. Она выравнивает нагрузку и не теряет задачи при всплеске.
• Снижайте конкурентность. Восемь параллельных воркеров упираются в лимит чаще, чем два, — и суммарно проходят меньше запросов из-за повторов. Начните с двух и поднимайте, пока 429 не появится.
• Считайте max_tokens. Значение по умолчанию в SDK часто больше, чем нужно задаче. Реалистичный потолок освобождает окно TPM почти мгновенно.

Бюджеты на ключ

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

Месячный бюджет

Потолок расхода в рублях за календарный месяц. Обнуляется первого числа

Дневной лимит

Страховка от разогнавшегося цикла. Обнуляется в полночь по московскому времени

RPM и TPM ключа

Свои пороги ниже аккаунтских — чтобы фоновая задача не забирала окно у продуктового трафика

Уведомления

Письмо при достижении 80% бюджета и при исчерпании

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

Выделенные лимиты

Для команд, которым стандартных порогов не хватает, лимиты выносятся в договор. Это не «попросить побольше», а отдельная ёмкость под ваш профиль нагрузки.

• RPM и TPM под нагрузку. Пороги считаются по вашему пиковому профилю, а не по общей планке.
• Конкурентность. Отдельное число одновременных запросов — критично для стриминга в интерфейсе.
• SLA в договоре. Доступность и время реакции поддержки зафиксированы документом, а не обещанием на сайте.

Чтобы обсудить пороги, напишите с описанием сценария: сколько запросов в пике и какие модели. Ответим с расчётом и условиями.