#Что означает ошибка
429 rate limit
Ошибка API 429 имеет две разные причины: rate_limit_exceeded (слишком много запросов или токенов в единицу времени) и insufficient_quota (закончились средства или лимит расходов на аккаунте). Лечатся они по-разному, поэтому смотрите на поле error.type и error.code в теле ответа.
Не повторяйте запросы вслепую: при нехватке квоты повтор не поможет.
Ниже диагностика и защитный код.
429 означает превышение лимита запросов или исчерпание квоты. Добавьте экспоненциальные повторы, ограничьте параллелизм и проверьте баланс.
#Причины и решения
| Возможная причина | Как узнать | Что делать |
|---|---|---|
| Лимит запросовRPM. | 429. | Повторы. |
| Исчерпана квотаБаланс. | 429. | Пополните. |
| ПараллелизмПотоки. | 429. | Ограничьте. |
| Большие запросыТокены. | 429. | Сократите. |
#Пошаговое решение
- Прочитайте тело ошибкиОткройте журнал ошибки API на стороне вашего приложения либо ответы в консоли разработчика и запишите статус HTTP, текст поля
error.type/error.codeи заголовки ограничения, если они присутствуют. Различайте временное превышение частоты запросов (rate_limit) и отсутствие оплаченной квоты (insufficient_quota): они могут возвращать одинаковый код 429, но решаются по-разному. Не публикуйте токен доступа в отчёте. - Проверьте баланс и лимиты расходовЗайдите в личную консоль именно того поставщика API, чей адрес указан в запросе. Найдите раздел расходов, оплаты и лимитов проекта; проверьте, есть ли доступный баланс, не истёк ли платёжный способ и не установлен ли нулевой лимит расходов. Если указано
insufficient_quota, ожидание и автоматические повторы обычно не помогут — нужно исправить доступную квоту или условия тарифа. - Проверьте, чей ключ используетсяВ настройках приложения найдите идентификатор проекта или организации, с которыми связан ключ, и сравните с тем проектом, где вы смотрите расходы. Если ключ хранится в переменной среды, проверьте её наличие без вывода самого секрета. Не вставляйте ключ в публичные журналы и не посылайте его в чат поддержки. При сомнениях создайте новый ключ в нужном проекте и безопасно замените только в своём приложении.
- Добавьте повторы с задержкойТолько для временного
rate_limit: прочитайте заголовокRetry-After, если он указан, и отложите следующий запрос на рекомендованное время. В программном клиенте добавьте ограниченное число повторов с увеличивающейся задержкой и случайной добавкой; не повторяйте запрос бесконечно и учитывайте возможность двойного списания или повторной операции. Дляinsufficient_quotaне запускайте автоматические повторы. - Снизьте параллелизмЕсли ошибка возникает при параллельных заданиях, сократите число одновременных запросов в очереди приложения, затем повторите один тестовый запрос и оцените ответ. Сверьте лимиты не только в запросах в минуту, но и в токенах/объёме данных, если провайдер их использует. При сохранении 429 выпишите временную метку, модель, проект и идентификатор запроса (без секретных данных) для поддержки.
#Квота
Если insufficient_quota, откройте страницу биллинга своего провайдера: пополните баланс, проверьте включённый платёжный метод, месячный лимит расходов и срок действия бесплатных кредитов. Убедитесь, что ключ принадлежит нужной организации и проекту: ключ другого проекта использует его квоту. После пополнения подождите несколько минут.
#Лимиты скорости
При rate_limit_exceeded читайте заголовки ответа: Retry-After, а также значения оставшихся лимитов запросов и токенов (названия различаются у провайдеров). Уменьшите параллелизм, добавьте очередь с ограничением RPM/TPM, повышайте уровень использования (tier) по правилам провайдера. Используйте пакетные (batch) эндпоинты для фоновых задач.
#Код
Реализуйте повторы с экспоненциальной задержкой и джиттером, но только для 429/5xx; для insufficient_quota прекращайте. Логируйте идентификатор запроса. Не используйте один ключ на много независимых сервисов: распределяйте по проектам. Храните ключ в переменных окружения, а не в клиентском коде. Проверьте запрос командой curl -i и найдите заголовки лимитов.