Rate limits

Hubris не применяет искусственных rate-limit-ов на пользовательские API-ключи. Стандартный тариф даёт неограниченное число запросов в секунду — расход ограничен только балансом.

Что реально ограничивает запросы

1. Баланс

Каждый запрос списывает с баланса фактическую стоимость. При недостаточном балансе (< 100 копеек) запрос отклоняется с 402 insufficient_balance ДО обращения к модели. Подробнее — на странице Биллинг.

2. Лимиты провайдера

Каждая модель имеет собственные ограничения от провайдера: requests-per-minute, tokens-per-minute, concurrent connections. При превышении провайдер возвращает 429, мы транслируем это как 502 upstream_error.

Что делать: добавить retry с экспоненциальным backoff. Hubris агрегирует трафик многих клиентов через свой сервисный ключ — вероятность упереться в лимит провайдера ниже, чем при работе напрямую.

3. Лимит расхода ключа с периодом сброса

У любого ключа можно задать лимит расхода в копейках и период его сброса:

Например, limit_kopecks: 5000 с периодом day — 50 ₽ в сутки; с периодом none — 50 ₽ на всю жизнь ключа. Превышение возвращает 429: код daily_limit_exceeded для суточного лимита и key_limit_exceeded для остальных периодов:

{
  "error": {
    "message": "Превышен лимит расхода этого API-ключа за месяц",
    "type": "rate_limit_error",
    "code": "key_limit_exceeded"
  }
}

Заголовок Retry-After — секунды до сброса окна; у лимита без сброса заголовка нет: повторять запрос бессмысленно, надо поднять лимит.

Это используется для:

• CI-runner-ов, чтобы утечка ключа не разорила баланс.
• Внутренних скриптов с ограниченным бюджетом — например, месячным.
• Ключей подрядчиков и демо с лимитом на весь срок.

Окна календарные, а не скользящие: суточный лимит сбрасывается в московскую полночь целиком, а не «отпускает» постепенно. В счётчик входят только успешно оплаченные запросы. Расход кешируется на 60 секунд, то есть кабинет и проверка могут отставать от точного значения на минуту.

Задать или поменять лимит — на странице API-ключи: поле «Лимит расхода, ₽» с выбором сброса в форме создания и на странице ключа. Очистите поле, чтобы снять лимит. По API — поля limit_kopecks и limit_period в Management API.

Генерация изображений (modalities: ["image"] / ["image","text"]) учитывается в расходе ключа на общих основаниях: одна сгенерированная картинка добавляется к расходу по итоговой стоимости (см. Генерация изображений).

Стратегия retry

Если получили 429 от Hubris (daily_limit_exceeded / key_limit_exceeded) или 502 (от провайдера):

import time

def with_retry(fn, max_attempts=3):
    delay = 1
    for attempt in range(max_attempts):
        try:
            return fn()
        except APIError as e:
            if e.code in ("upstream_error", "upstream_timeout"):
                if attempt < max_attempts - 1:
                    time.sleep(delay)
                    delay *= 2
                    continue
            raise

Не делайте retry на:

• invalid_api_key (401) — ключ не починится сам.
• insufficient_balance (402) — пополните баланс сначала.
• model_not_found (404) — название не изменится.
• invalid_request (400) — баг в коде.

Concurrent requests

Параллельные запросы на одном ключе — без ограничений. Если ваш сервис делает 100 запросов одновременно, они все пойдут к моделям параллельно. Узкое горлышко — провайдер модели, не Hubris.

Что дальше

• Ошибки — все коды и стратегия retry.
• Биллинг — про баланс.
• Аутентификация — про создание ключей.

Обновлено: 13 мая 2026 г.