Лимиты и код 429

429 в Lumean API — не одно ограничение, а пять. У них разные причины, разные тела ответа и, главное, разное лечение: то, что чинит один, бесполезно против остальных четырёх. Универсальный «подождать и повторить» гарантированно работает ровно в двух случаях из пяти.

Как отличить за один взгляд

Достаточно двух проверок в таком порядке: есть ли в теле поле reason и пришёл ли заголовок Retry-After. Первая проверка отделяет лимит частоты от четырёх «заказных» ограничений, вторая — говорит, можно ли просто подождать.

Пять источников

Частота запросов ключа

Ограничение по окнам limits.requests.per_minute|per_hour|per_day самого ключа. Тело — голый конверт { "success": false, "message": "…" }: ни reason, ни Retry-After, ни X-RateLimit-*. Ориентируйтесь на настроенные окна ключа и делайте экспоненциальный backoff сами.

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

Токен-квота ключа

Считает не запросы, а токены — учётную единицу объёма работы (это не деньги и не LMC). Окна per_minute, per_hour, per_day, per_month берутся из limits.tokens.* ключа. Проверка идёт до создания: заказ не создаётся и не тарифицируется.

В теле приходит window (первое нарушенное окно), limit, used, requested, reset_at и retry_after — этого достаточно, чтобы поставить задачу в очередь до точного момента, а не опрашивать API вслепую.

Usage-лимит подписки

Не про ключ, а про тарифный план: месячный объём генерации исчерпан. Тело содержит только message и reason: "limit_exceeded" — ни полей квоты, ни Retry-After. Пауза не поможет: до конца расчётного периода ответ не изменится.

Слоты одновременных задач

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

Действующий потолок и текущее число активных — в GET /usage, запись с limit_type: "concurrent". У неё period_start, period_end и resets_in равны null: периода у такого лимита нет, ждать «конца месяца» бессмысленно.

Кулдаун контентной политики

Пять подряд заблокированных политикой задач ограничивают создание новых на 5 минут, при повторных залётах — на 10, затем на 15 (выше не поднимается). Это единственный «заказной» 429, который несёт Retry-After, а также поля retry_after (секунды) и retry_at (ISO-8601).

Сбои инфраструктуры счётчик не двигают: считаются только контентные блокировки, а любая успешная задача обнуляет и счётчик, и достигнутую ступень.

Что делать интегратору

1. Читайте reason раньше, чем Retry-After: он один отвечает на вопрос «это про частоту, объём, план, параллелизм или текст».
2. Уважайте Retry-After, когда он есть. Когда его нет, ретрай по таймеру помогает только при лимите частоты — в остальных случаях нужен GET /usage или правка текста.
3. Не путайте 429 с 402. Код 402 payg_topup_required — это не отказ, а развилка оплаты: сервер предлагает доплатить недостающие токены из LMC-баланса. Слепой ретрай здесь бесполезен, нужен повтор с confirm_payg_topup и quote_token.
4. Ставьте потолок попыток. Три из пяти источников не рассасываются сами по себе, и бесконечный цикл ретраев не приблизит выполнение заказа ни на секунду.