RU ▾
Получить API-ключ

Ошибка LLM API 429: причины и способы устранения

Ошибка LLM API 429 означает, что сервер временно отказывает в запросе, а не навсегда. В этом API есть три различные причины, и для каждой требуется своё решение.

Обновлено

Пакеты данных, ожидающие в очереди у шлюза с восемью полосами, иллюстрирующие лимиты API

Ключевые моменты

Три вида 429

HTTP 429 — стандартный статус «слишком много запросов». Здесь он охватывает три ситуации, а JSON-тело ошибки указывает, какая именно произошла.

Код ошибкиЧто это означаетТипичное решение
rate_limitedСлишком много запросов в минутуЗамедлите темп, распределите запросы в течение минуты
concurrencyСлишком много одновременных запросовСнизьте параллелизм, дождитесь освобождения слотов
Перегрузка с заголовком Retry-After: 5Временная нагрузка на сервис, не по вашей винеПодождите количество секунд из заголовка, затем повторите

Сначала прочитайте код, так как решение для одной причины не поможет для другой. Уменьшение количества запросов в минуту не поможет, если реальная проблема — 20 рабочих потоков, работающих одновременно.

Знайте свои лимиты

Лимиты зависят от типа ключа:

  • Полный ключ: 8 параллельных запросов и 300 запросов в минуту.
  • Пробный ключ: 2 параллельных запроса и 60 запросов в минуту.

Каждый ответ содержит заголовки X-RateLimit-Limit-Requests и X-RateLimit-Limit-Concurrency, чтобы ваш клиент мог считывать верхнюю границу, а не хардкодить её. Пробный ключ — частая причина проблем у новых пользователей: скрипт, который работает нормально при выполнении 1 запроса за раз, начинает падать, когда вы добавляете пул потоков на 4. Пробный ключ предназначен для тестирования, а полный ключ предоставляется при любом пополнении от $20 (суммы и бонусы указаны на странице с ценами).

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

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

Обычный запрос удерживает слот параллелизма одну-две секунды. Потоковый запрос (stream: true) удерживает его до тех пор, пока не прибудет последний токен и поток не закроется. Долгий ответ может занимать слот десятки секунд, поэтому 8 слотов быстро исчезнут в чат-приложении с несколькими активными пользователями.

Две ошибки вызывают большинство проблем здесь. Первая — оставление потока без закрытия: если клиент перестает читать, но оставляет соединение открытым, слот остается занятым до завершения соединения. Всегда закрывайте ответ в блоке finally или используйте контекстный менеджер SDK. Вторая — повторная попытка потока путем открытия второго, пока первый еще жив, что удваивает использование слотов именно тогда, когда они в дефиците.

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

Код повтора на Python с экспоненциальной задержкой

Схема проста: перехватите код 429, прочитайте код, подождите, повторите запрос с увеличивающейся задержкой и некоторой случайностью, а после нескольких попыток сдайтесь. Этот вариант использует официальный пакет openai против базового URL сервиса:

import random
import time
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.onekeyllmapi.com/v1",
    api_key="YOUR_KEY",
    max_retries=0,  # we handle retries ourselves
)

def chat(messages, attempts=5):
    for i in range(attempts):
        try:
            r = client.chat.completions.create(
                model="uncensored",
                messages=messages,
            )
            return r.choices[0].message.content
        except RateLimitError as e:
            headers = e.response.headers
            wait = float(headers.get("Retry-After", 0))
            if not wait:
                wait = min(30, 2 ** i)  # 1, 2, 4, 8, 16 seconds
            wait += random.uniform(0, 1)  # jitter
            time.sleep(wait)
    raise RuntimeError("still rate limited after retries")

print(chat([{"role": "user", "content": "Reply with the word ok."}]))

Когда заголовок присутствует, используйте его как минимальное ожидание. Когда его нет, экспоненциальная задержка работает для rate_limited, так как окно в минуту сдвигается. Разброс предотвращает одновременный повтор запроса многими рабочими потоками.

Ограничьте параллельные вызовы, чтобы редко видеть 429

Повторы лечат симптом. Семафор предотвращает большую часть проблем, никогда не отправляя больше запросов, чем количество ваших слотов. Установите его немного ниже лимита, чтобы у повтора или случайного запроса оставалось место:

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(
    base_url="https://api.onekeyllmapi.com/v1",
    api_key="YOUR_KEY",
)
sem = asyncio.Semaphore(6)  # full key allows 8; use 1 on a trial key

async def ask(prompt):
    async with sem:
        r = await client.chat.completions.create(
            model="uncensored",
            messages=[{"role": "user", "content": prompt}],
        )
        return r.choices[0].message.content

async def main():
    prompts = [f"Give one fact about the number {n}." for n in range(50)]
    results = await asyncio.gather(*(ask(p) for p in prompts))
    print(len(results))

asyncio.run(main())

Для лимита в минуту 300 запросов в минуту — это в среднем 5 в секунду. Если вы пакетно обрабатываете тысячи коротких задач, добавьте небольшой sleep или bucket токенов перед семафором. Поскольку SDK по умолчанию также выполняет повторные попытки самостоятельно, установите max_retries явно, чтобы ваша логика и SDK не накладывались друг на друга и не умножали задержки.

Воспроизведение и анализ 429 через curl

Прежде чем менять код, посмотрите на исходный ответ. Добавьте -i к curl, чтобы печатались заголовки, и выполните несколько запросов параллельно, чтобы намеренно вызвать ошибку:

for i in 1 2 3 4; do
  curl -i -s https://api.onekeyllmapi.com/v1/chat/completions     -H "Authorization: Bearer $API_KEY"     -H "Content-Type: application/json"     -d '{"model":"uncensored","messages":[{"role":"user","content":"Count to 200 slowly."}]}' &
done
wait

На пробном ключе, который позволяет 2 запроса одновременно, третий и четвёртый вызовы должны вернуть статус 429 и код ошибки concurrency. На полном ключе вам потребуется более 8 одновременно. Посмотрите на три вещи в каждом ответе: строку статуса, заголовок Retry-After, если он есть, и поле error.code в теле JSON. Этот небольшой эксперимент расскажет больше, чем час угадываний, и даст воспроизводимый случай для обращения в поддержку, если что-то выглядит неправильно.

Проектируйте с учетом этого, а не вокруг него

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

Краткий чек-лист отладки

  1. Логируйте полное тело ошибки и заголовок X-Request-Id для каждого 429. Поле code разделяет rate_limited и concurrency.
  2. Проверьте, является ли ваш ключ пробным. Если да, ожидайте 2 параллельных запроса и 60 в минуту.
  3. Посчитайте все программы, использующие ключ, а не только ту, которая дала сбой.
  4. Ищите незакрытые потоки и циклы, которые повторяют запрос мгновенно без задержки. Цикл мгновенных повторов превращает одну 429 в сотню.
  5. Подтвердите баланс с помощью X-Balance-USD или GET /v1/balance. Пустой баланс — это другая проблема, чем 429, но проверка занимает секунды.

Неудачные запросы не оплачиваются, поэтому повторные попытки не расходуют ваши токены за отклоненные попытки. Полный список кодов состояния и заголовков см. в документации. Если вам нужен ключ с более высокими лимитами, чем у пробного, получите API-ключ и пополните баланс.

Вопросы и ответы

Это ошибка 429 по моей вине или провайдера?

Возможны оба варианта. Коды rate_limited и concurrency означают, что ваш ключ превысил лимит. 429 с заголовком Retry-After также может возникать при временной перегрузке; в этом случае нужно подождать указанное время и повторить запрос.

Сколько ждать перед повторной попыткой?

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

Стоят ли деньги отклонённые запросы?

Нет. За неудачные или отклонённые запросы плата не взимается.

Могу ли я увеличить лимиты?

Полный ключ позволяет 8 параллельных запросов и 300 в минуту, по сравнению с 2 и 60 для пробного ключа. После превышения этих лимитов распределите нагрузку через очередь на вашей стороне.

Ваш ключ — всего в одной форме

Создайте аккаунт, скопируйте ключ, измените базовый URL. Это вся настройка.