Лимиты запросов и переключение

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

Лимиты, которые вы задаёте для ключа#

Для каждого ключа можно задать лимит Запросов в минуту и лимит Макс. число параллельных запросов. Они настраиваются в разделе Лимиты и ограничения при создании или редактировании ключа на странице API-ключи. По умолчанию оба выключены.

Запрос, упёршийся в лимит, ждёт свободного места до 2 секунд. Если место не освободилось, он завершается ошибкой 429 с сообщением This API key has reached its rate or concurrency limit. и заголовком retry-after в секундах. Используйте отдельные ключи с собственными лимитами, чтобы одна нагрузка не вытесняла другую. Остальные настройки ключей описаны в разделе API-ключи.

Очередь ожидания мощности#

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

В общей сложности запрос ждёт мощности не более 10 секунд. Если он принят, ответ содержит x-lovely-queued-ms со временем ожидания. Если нет, запрос завершается ошибкой 429 с сообщением All upstream capacity for this model is busy. Retry shortly. и заголовком retry-after.

Запросы в очереди не тарифицируются, пока не начнут выполняться, а запрос, отклонённый с 429, не тарифицируется вовсе.

Автоматическое переключение#

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

• не отвечает за отведённое время, недоступен или возвращает 408, 409, 425, 429 либо любой 5xx;
• отклоняет запрос по причинам на своей стороне, а не на вашей;
• отказывает во время потока до первого токена (см. Потоковая передача).

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

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

• Сам запрос некорректен. Если модель отклоняет его с 400, 404, 413 или 422, повтор в другом месте закончится так же. Вы получаете этот статус с причиной.
• Поток уже начался. После первого токена запрос закреплён за своим каналом. Более поздний сбой приходит как событие ошибки внутри потока.

Коды статуса#

Тип ошибки соответствует формату вашего API: rate_limit_error (Anthropic), rate_limit_exceeded (OpenAI) или RESOURCE_EXHAUSTED (Gemini) для 429 и api_error (UNAVAILABLE в Gemini) для 502. Полный список — в разделе Ошибки.

Повторы на стороне клиента#

Шлюз уже повторяет запросы на разных каналах, поэтому 429 или 502 означает, что проблема сохранялась на протяжении нескольких попыток. Повторите запрос ещё несколько раз с экспоненциальной задержкой и случайным разбросом (jitter) и соблюдайте retry-after, если он есть.

SDK Anthropic и OpenAI делают это по умолчанию, дважды повторяя 408, 409, 429 и 5xx. Для пакетных задач увеличьте это число:

import os
from openai import OpenAI

client = OpenAI(base_url="https://lovelyrouter.com/v1", api_key=os.environ["LOVELY_API_KEY"], max_retries=5)

При работе через обычный HTTP реализуйте ту же политику:

# --retry covers 429 and 5xx and honors retry-after
curl --retry 5 --retry-max-time 120 https://lovelyrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model": "gpt-6.1-sol", "messages": [{"role": "user", "content": "Hi"}]}'

В потоках повторяйте запрос, только если ошибка пришла до какого-либо содержимого. Если поток оборвался на середине, частичный вывод уже оплачен; решите, сохранить его или запросить весь ответ заново.

Баланс и лимиты расходов#

Перед выполнением каждый запрос проверяет ваш баланс и лимит расходов ключа. Если баланс на нуле или ниже либо ключ исчерпал свой лимит, запрос завершается ошибкой 402: Insufficient balance. Top up at the dashboard. или This API key has reached its spend limit. Тип ошибки — insufficient_quota в формате OpenAI, billing_error в формате Anthropic и RESOURCE_EXHAUSTED в формате Gemini.

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