Limits — Rate Limits и Кредитные Лимиты

Документация по ограничениям API-прокси ru-openrouter.ru.

Содержание

• Типы лимитов
• Проверка своих лимитов
• Кредитные лимиты
• Rate Limits
• Лимиты API-ключа
• Лимиты запросов
• Обработка ошибок

Типы лимитов

API использует несколько уровней ограничений:

Проверка своих лимитов

Баланс и кредитные лимиты

curl https://api.ru-openrouter.ru/v1/user/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

Ответ:

{
  "user": "user@example.com",
  "balance": 150.50,
  "currency": "RUB"
}

Rate Limit заголовки

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

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1700000120

Заголовок X-RateLimit-Remaining показывает, сколько запросов ещё можно сделать в текущем окне. Когда он достигает 0, следующий запрос будет отклонён с ошибкой 429.

При превышении лимита дополнительно добавляется заголовок Retry-After с количеством секунд до сброса окна:

Retry-After: 45

Кредитные лимиты

Кредитные лимиты определяют, сколько вы можете потратить. Баланс пополняется в рублях (RUB).

Проверка баланса

Перед каждым платным запросом система проверяет, достаточно ли средств на балансе для его выполнения.

Автоматический расчёт max_tokens

Если параметр max_tokens не указан в запросе, система автоматически рассчитывает максимальное количество выходных токенов, которое пользователь может себе позволить исходя из текущего баланса.

Ошибка 402

{
  "error": {
    "code": 402,
    "message": "Недостаточно средств на балансе. Требуется: 1.50 ₽, Доступно: 1.40 ₽. Пожалуйста, пополните баланс.",
    "metadata": {
      "error_type": "insufficient_balance"
    }
  }
}

Что делать:

• Пополните баланс в личном кабинете
• Уменьшите max_tokens в запросе
• Выберите более дешёвую модель

Rate Limits

Rate limits регулируют количество запросов, которое можно отправить за определённый промежуток времени.

Как это работает

• Скользящее окно: учитываются запросы за последние N секунд

Ошибка 429

{
  "error": {
    "code": 429,
    "message": "The service is receiving too many requests from you. Too many requests. Please try again in 45 seconds.",
    "metadata": {
      "error_type": "rate_limit_exceeded"
    },
    "retry_after": 45
  }
}

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

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1700000120
Retry-After: 45

Что делать:

• Дождаться указанного в Retry-After времени
• Использовать экспоненциальную задержку (backoff) при повторных попытках
• Распределять нагрузку между разными моделями

Лимиты API-ключа

Для каждого API-ключа могут быть установлены индивидуальные кредитные лимиты.

Как это работает

• При создании ключа в личном кабинете можно указать максимальную сумму расходов
• Лимит может быть:
  • Фиксированным — ключ работает до исчерпания лимита
  • Периодическим — лимит сбрасывается каждый день/неделю/месяц
  • Без лимита — unlimited

Проверка лимита ключа

curl https://api.ru-openrouter.ru/v1/user/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

Проверка происходит автоматически перед каждым платным запросом. Если лимит исчерпан, возвращается ошибка:

{
  "error": {
    "code": 429,
    "message": "API key limit exceeded: ...",
    "metadata": {
      "error_type": "limit_exceeded"
    }
  }
}

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

Контекстное окно модели

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

{
  "error": {
    "code": 400,
    "message": "Input tokens exceed model context limit. Model: 'openai/gpt-4o', Context length: 128000 tokens, Input tokens: 130000 (max allowed: 121600). Reduce message length.",
    "metadata": {
      "error_type": "input_tokens_exceeded"
    }
  }
}

max_tokens = -1 (без лимита)

Если передать max_tokens: -1, система автоматически рассчитает безопасное значение контекстного окна модели.

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

Размер тела запроса

Content-Type

Разрешённые типы содержимого:

• application/json — для всех эндпоинтов
• application/json; charset=utf-8
• multipart/form-data — только для аудио-эндпоинтов (transcriptions, translations)

При неверном Content-Type:

{
  "error": {
    "code": 415,
    "message": "Unsupported Media Type. Only application/json is allowed.",
    "metadata": {
      "error_type": "unsupported_media_type"
    }
  }
}

Защита от неавторизованных запросов (бот-защита)

Для предотвращения перебора API-ключей действует система блокировки по IP при большом количестве неавторизованных запросов. После превышения лимита попыток IP временно блокируется.

Обработка ошибок

Краткая таблица