Три вида 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 слотов для остальных.
Краткий чек-лист отладки
- Логируйте полное тело ошибки и заголовок
X-Request-Idдля каждого 429. Поле code разделяетrate_limitedиconcurrency. - Проверьте, является ли ваш ключ пробным. Если да, ожидайте 2 параллельных запроса и 60 в минуту.
- Посчитайте все программы, использующие ключ, а не только ту, которая дала сбой.
- Ищите незакрытые потоки и циклы, которые повторяют запрос мгновенно без задержки. Цикл мгновенных повторов превращает одну 429 в сотню.
- Подтвердите баланс с помощью
X-Balance-USDилиGET /v1/balance. Пустой баланс — это другая проблема, чем 429, но проверка занимает секунды.
Неудачные запросы не оплачиваются, поэтому повторные попытки не расходуют ваши токены за отклоненные попытки. Полный список кодов состояния и заголовков см. в документации. Если вам нужен ключ с более высокими лимитами, чем у пробного, получите API-ключ и пополните баланс.
