Ошибка 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.
Что спросить у провайдера перед покупкой
Передайте ожидаемые запросы за минуту, размеры входа и выхода, параллельность и допустимое время ожидания. Попросите подтвердить:
- Квоты для выбранной модели и оплачиваемого маршрута.
- Что входит в лимит токенов и как учитывается кеш.
- Какие ограничения общие для нескольких ключей и моделей.
- Правила коротких всплесков и повышения нагрузки.
- Коды ошибок, заголовки для повторов и порядок увеличения квоты.
Для большого фонового задания проверьте Batch API: у него собственные условия очереди и сроки. Для чата учитывайте и скорость ответа, поскольку длинное выполнение дольше занимает доступную параллельность.
В каталоге API найдите модели и провайдеров с подходящими ставками. Затем подтвердите квоты у выбранного сервиса: цена токена сама по себе не показывает, выдержит ли маршрут нагрузку вашего приложения.
