Справочник API

Лимиты запросов

Ознакомьтесь с тем, как работают лимиты запросов и квота аккаунта в TokSpan, а также как корректно обрабатывать ответы 429 в ваших приложениях.

Как работают лимиты

TokSpan ограничивает объём запросов и квоту аккаунта, чтобы ни один клиент не мог перегрузить общую инфраструктуру. Применяются три вида лимитов:

  • Лимиты запросов на аккаунт — максимальное число запросов, которое аккаунт может выполнить за временное окно (запросов/мин и токенов/мин, настраивается для тарифа/группы).
  • Лимиты upstream-провайдеров — каждый провайдер моделей применяет собственные потолки пропускной способности. Если провайдер перегружен, запросы могут вставать в очередь или возвращать 429.
  • Баланс / квота аккаунта — каждый запрос расходует небольшую часть баланса по мере использования токенов. Когда баланс достигает нуля, запросы отклоняются.

Обработка ответов 429

Ответ 429 Too Many Requests означает, что вы достигли лимита запросов или исчерпали квоту. Ответ может содержать заголовок Retry-After, указывающий, сколько секунд нужно подождать. Рекомендуемая обработка:

  1. Проверьте заголовок Retry-After, если он присутствует, и подождите указанное время перед повторной попыткой.
  2. В противном случае повторяйте с экспоненциальной задержкой и джиттером (например, 1с → 2с → 4с, с небольшим случайным сдвигом), чтобы повторы не создавали «эффект толпы».
  3. Если вы стабильно упираетесь в лимиты в продакшене, свяжитесь с нами, чтобы повысить лимит запросов аккаунта.

Недостаточно баланса / квоты

Когда баланс аккаунта или API-ключа исчерпан, запросы отклоняются. Ответ об ошибке использует тип new_api_error с сообщением, упоминающим квоту или баланс (например, insufficient_user_quota). Это не лимит запросов — повторные попытки не помогут, пока вы не пополните баланс.

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

Запрос более высоких лимитов

Нужны более высокие лимиты для продакшена? Свяжитесь с поддержкой с вашим email аккаунта и ожидаемым объёмом запросов — мы скорректируем лимиты или настроим корпоративный тариф.