Ошибка 429 при положительном балансе: почему API перестаёт отвечать

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

Очередь фиолетовых карточек перед узкими стеклянными воротами и стопки монет рядом

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

Примеры нагрузки ниже заданы для объяснения расчёта и не являются лимитами конкретного российского провайдера.

Один статус 429 может означать разные причины

OpenAI отдельно документирует превышение скорости, резкий рост трафика, исчерпанный баланс и ограничения расходов организации или проекта. Эти причины могут иметь одинаковый HTTP-статус. Смотрите error.code, error.type и сообщение, а не только число 429. Коды ошибок OpenAI.

Что сообщил API Что проверить Что делать
Превышена скорость запросов или токенов Трафик всех приложений в той же области лимита Снизить скорость, поставить задачи в очередь
Нагрузка выросла слишком резко Всплеск после запуска задания или смены маршрута Наращивать трафик постепенно
Исчерпаны средства Баланс, проект и учётная запись, к которым относится ключ Восстановить оплату для нужной учётной записи
Достигнут лимит расходов Бюджет проекта или организации Пересмотреть лимит или дождаться его сброса
Достигнута квота тарифа Условия доступа и порядок повышения квоты Запросить изменение условий у провайдера

Названия полей и статусы у другого API могут отличаться. Например, Claude документирует 429 при достижении установленного платформой потолка расходов, но для собственного лимита пользователя на Messages API описывает 400. Правила Claude. Привяжите обработчик к документации вашего маршрута.

Какие лимиты ограничивают приложение

RPM означает число запросов в минуту, TPM означает число токенов в минуту. Для разных типов данных сервис может считать изображения или минуты аудио отдельно. Метрики OpenAI. Кроме этих показателей, при выборе сервиса проверяйте дневные квоты и ограничения одновременных запросов.

Ограничение Как его заметить в продукте
Запросы за период Много коротких сообщений быстро расходуют квоту
Токены за период Несколько больших документов занимают доступный объём
Одновременные запросы Новые задачи ждут, пока завершатся уже запущенные
Дневная квота Доступ не возвращается после короткой паузы
Допустимый всплеск Ровный поток работает, резкий пакет получает ошибки

У Claude входные и выходные токены ограничиваются раздельно: ITPM и OTPM. Правила учёта кеша тоже зависят от модели. Лимиты Messages API. Поэтому число «токенов в минуту» нужно читать вместе с определением того, какие токены оно включает.

У OpenAI ограничения действуют на уровне организации и проекта. У Gemini квоты применяются к проекту, а не к отдельному ключу. Создание ещё одного ключа в той же области квоты её не увеличивает. OpenAI, Gemini.

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

Как оценить пропускную способность до запуска

Зададим условный маршрут с такими условиями:

  • 60 запросов в минуту;
  • 60 000 учитываемых токенов в минуту;
  • 4 одновременных запроса;
  • 2 000 учитываемых токенов и 5 секунд занятости на один запрос.

Для ровного потока получаются три оценки:

Ограничение Расчёт Верхняя оценка
Запросы По условию 60 в минуту
Токены 60 000 ÷ 2 000 30 в минуту
Параллельность 4 × 60 ÷ 5 48 в минуту

В этом сценарии поток ограничивают токены: около 30 запросов в минуту. Это оценка для заданных одинаковых запросов без всплесков и накладных расходов. Для рабочего лимита нужен запас на длинные ответы и колебания времени.

Подставляйте объём, который API использует при проверке квоты. Он может отличаться от фактического списания. В частности, OpenAI описывает оценку ограничения с учётом max_tokens и размера входа. Завышенный предел ответа способен занять больше квоты, чем ожидает приложение. Правило расчёта OpenAI.

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

Что сохранить при первой ошибке

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

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

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

Как повторять временно отклонённые запросы

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

Согласуйте повторы приложения с повторами SDK. Учебный пример: приложение делает 3 попытки, а на каждой SDK допускает ещё 2 повтора. Тогда одна задача может отправить 3 × 3 = 9 HTTP-запросов. Это заданная конфигурация, а не обещание поведения любой библиотеки.

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

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

Что спросить у провайдера перед покупкой

Передайте ожидаемые запросы за минуту, размеры входа и выхода, параллельность и допустимое время ожидания. Попросите подтвердить:

  1. Квоты для выбранной модели и оплачиваемого маршрута.
  2. Что входит в лимит токенов и как учитывается кеш.
  3. Какие ограничения общие для нескольких ключей и моделей.
  4. Правила коротких всплесков и повышения нагрузки.
  5. Коды ошибок, заголовки для повторов и порядок увеличения квоты.

Для большого фонового задания проверьте Batch API: у него собственные условия очереди и сроки. Для чата учитывайте и скорость ответа, поскольку длинное выполнение дольше занимает доступную параллельность.

В каталоге API найдите модели и провайдеров с подходящими ставками. Затем подтвердите квоты у выбранного сервиса: цена токена сама по себе не показывает, выдержит ли маршрут нагрузку вашего приложения.

Частые вопросы

Почему API отвечает 429, если баланс положительный?

Баланс и ограничения нагрузки проверяются отдельно. Можно превысить число запросов или токенов, достигнуть лимита расходов проекта либо попасть под ограничение резкого роста нагрузки. Точную причину показывает тело ошибки.

Поможет ли новый API-ключ?

Только если проблема относится к самому ключу. Новый ключ внутри того же проекта или организации обычно не меняет общую квоту: проверяйте область действия лимита в документации сервиса.

Нужно ли автоматически повторять любой запрос с 429?

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

Можно ли отправить весь минутный лимит запросов одновременно?

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

Читайте также