429/Ошибка емкости: правильные ожидания ротации аккаунтов и заблуждения об исчерпании емкости модели

Чему вы научитесь

• Правильно различать "недостаток квоты" и "ограничение скорости апстрима"
• Понять механизм автоматической ротации Antigravity Tools и ожидаемое поведение
• При возникновении ошибки 429 знать, как быстро найти проблему и оптимизировать конфигурацию

Ваша текущая проблема

• Видите ошибку 429, думаете, что "у модели нет емкости"
• Настроили несколько аккаунтов, но все равно часто сталкиваетесь с 429, не знаете, это проблема конфигурации или аккаунта
• Не понятно, когда система автоматически переключит аккаунт, а когда "застрянет"

Основная идея

Что такое ошибка 429?

429 Too Many Requests - это код состояния HTTP. В Antigravity Tools ошибка 429 означает не только "слишком много запросов", но и ряд сигналов "вы временно не можете использовать", таких как исчерпание квоты, временная перегрузка модели и т.д.

Прокси пытается определить причину 429

Прокси пытается разобрать error.details[0].reason или error.message из тела ответа, грубо разделяя 429 на несколько типов (фактически зависит от возвращаемого значения):

Тип, определяемый прокси	Распространенная reason / подсказка	Типичная характеристика
Исчерпание квоты	QUOTA_EXHAUSTED / текст содержит exhausted, quota	Возможно, нужно дождаться обновления квоты
Ограничение скорости	RATE_LIMIT_EXCEEDED / текст содержит per minute, rate limit, too many requests	Обычно период охлаждения в десятки секунд
Недостаток емкости модели	MODEL_CAPACITY_EXHAUSTED / текст содержит model_capacity	Обычно кратковременная перегрузка, позже можно восстановить
Неизвестно	Не удалось разобрать	Используется стратегия охлаждения по умолчанию

Автоматическая обработка в Antigravity Tools

Когда запрос сталкивается с 429 (а также с некоторыми 5xx/перегрузками), прокси обычно делает две вещи на стороне сервера:

1. Записать время охлаждения: Записать эту ошибку в RateLimitTracker, при последующем выборе аккаунта будет активно избегать аккаунтов, которые "все еще охлаждаются".
2. Ротация аккаунтов при повторной попытке: Handlers будут делать несколько попыток в рамках одного запроса, при повторной попытке force_rotate=true, тем самым запуская TokenManager выбрать следующий доступный аккаунт.

Как узнать, переключился ли аккаунт?

Даже если тело вашего запроса не изменилось, в ответе обычно есть X-Account-Email (и X-Mapped-Model), вы можете использовать его для проверки "какой аккаунт использовался в этом запросе".

Когда возникает ошибка 429?

Сценарий 1: Слишком частые запросы одного аккаунта

Симптом: Даже с одним аккаунтом отправка большого количества запросов за короткое время вызывает 429.

Причина: У каждого аккаунта есть собственное ограничение скорости (RPM/TPM), превышение приведет к ограничению.

Решение:

• Увеличить количество аккаунтов
• Снизить частоту запросов
• Использовать режим фиксированного аккаунта для распределения нагрузки (см. "Режим фиксированного аккаунта")

Сценарий 2: Одновременное ограничение всех аккаунтов

Симптом: Есть несколько аккаунтов, но все возвращают 429.

Причина:

• Общее количество аккаунтов недостаточно для вашей частоты запросов
• Почти все аккаунты одновременно вызывают ограничение/перегрузку

Решение:

• Добавить больше аккаунтов
• Изменить режим планирования на "Приоритет производительности" (пропустить липкие сессии и повторное использование окна 60s)
• Проверить, не исключает ли защита квоты доступные аккаунты

Сценарий 3: Аккаунт ошибочно помечен защитой квоты

Симптом: Квота определенного аккаунта достаточна, но система постоянно пропускает его.

Причина:

• Включена защита квоты, порог установлен слишком высоко
• Квота определенной модели этого аккаунта ниже порога
• Аккаунт вручную помечен как proxy_disabled

Решение:

• Проверьте настройки защиты квоты (Settings → Quota Protection), настройте порог и модели мониторинга в соответствии с интенсивностью использования
• В данных аккаунта проверьте protected_models, убедитесь, что он не пропущен политикой защиты

Делайте вместе со мной

Шаг 1: Определите тип ошибки 429

Зачем: Различные типы ошибок 429 требуют разной обработки.

В Proxy Monitor посмотрите тело ответа ошибки 429, сосредоточьтесь на двух типах информации:

• Причина: error.details[0].reason (например, RATE_LIMIT_EXCEEDED, QUOTA_EXHAUSTED) или error.message
• Время ожидания: RetryInfo.retryDelay или details[0].metadata.quotaResetDelay (если существует)

{
  "error": {
    "details": [
      {
        "reason": "RATE_LIMIT_EXCEEDED",
        "metadata": {
          "quotaResetDelay": "42s"
        }
      }
    ]
  }
}

Вы должны увидеть:

• Если в теле ответа можно найти время ожидания (например, RetryInfo.retryDelay или quotaResetDelay), прокси обычно сначала подождет короткое время, затем повторит попытку.
• Если времени ожидания нет, прокси добавит "период охлаждения" для этого аккаунта в соответствии со встроенной стратегией и при повторной попытке сразу перейдет к следующему аккаунту.

Шаг 2: Проверьте конфигурацию планирования аккаунтов

Зачем: Конфигурация планирования напрямую влияет на частоту ротации аккаунтов и приоритет.

Перейдите на страницу API Proxy, посмотрите стратегию планирования:

Элемент конфигурации	Описание	Значение по умолчанию / рекомендация
Scheduling Mode	Режим планирования	Balance (по умолчанию)
Preferred Account	Режим фиксированного аккаунта	Не выбрано (по умолчанию)

Сравнение режимов планирования:

Режим	Стратегия повторного использования аккаунтов	Обработка ограничения скорости	Применимые сценарии
CacheFirst	Включает липкие сессии и повторное использование окна 60s	Приоритет ожидания, значительно повышает коэффициент попадания Prompt Caching	Диалоговые / требующие высокого коэффициента попадания кэша
Balance	Включает липкие сессии и повторное использование окна 60s	Сразу переключается на альтернативный аккаунт, учитывая как успешность, так и производительность	Универсальный сценарий, по умолчанию
PerformanceFirst	Пропускает липкие сессии и повторное использование окна 60s, чистый режим round-robin	Сразу переключается, нагрузка на аккаунты наиболее равномерная	Высокая параллельность, бес状態ные запросы

Кэш-приоритет против балансового режима

Если вы используете Prompt Caching и хотите повысить коэффициент попадания кэша, выберите CacheFirst - при ограничении скорости он будет преимущественно ждать, а не сразу переключать аккаунт. Если вы больше цените успешность запроса, чем кэш, выберите Balance - при ограничении скорости он сразу переключит аккаунт.

Режим приоритета производительности

Если ваши запросы бес状態ные (например, генерация изображений, отдельные запросы), попробуйте PerformanceFirst. Он пропускает липкие сессии и повторное использование окна 60s, позволяя последовательным запросам легче попадать на разные аккаунты.

Шаг 3: Проверьте, нормально ли работает ротация аккаунтов

Зачем: Убедитесь, что система может автоматически переключать аккаунты.

Метод 1: Смотрите заголовки ответа

С помощью curl или своего клиента выведите заголовки ответа и посмотрите, меняется ли X-Account-Email.

Метод 2: Просмотрите логи

Откройте файл логов (в зависимости от вашей системы), найдите 🔄 [Token Rotation]:

🔄 [Token Rotation] Accounts: [
  "account1@example.com(protected=[])",
  "account2@example.com(protected=[])",
  "account3@example.com(protected=[])"
]

Метод 3: Используйте Proxy Monitor

На странице Monitor просмотрите логи запросов, обратите внимание на:

• Меняется ли поле Account между разными аккаунтами
• После запросов со статусом 429, есть ли успешные запросы, использующие разные аккаунты

Вы должны увидеть:

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

Шаг 4: Оптимизируйте приоритет аккаунтов

Зачем: Пусть система сначала использует аккаунты с высокой квотой/высоким уровнем, снижая вероятность 429.

В TokenManager система отсортирует пул аккаунтов перед выбором аккаунта (выведет 🔄 [Token Rotation] Accounts: ...):

1. Приоритет уровня подписки: ULTRA > PRO > FREE
2. Приоритет процента квоты: В пределах одного уровня, аккаунты с более высокой квотой идут первыми
3. Точка входа сортировки: Эта сортировка происходит на стороне прокси, окончательный выбор аккаунта зависит от сортировки + оценки доступности на стороне прокси.

Принцип умной сортировки (на стороне прокси)

Приоритет: ULTRA > PRO > FREE; В пределах одного уровня подписки по убыванию remaining_quota (максимальный процент оставшейся квоты аккаунта).

Действия:

• Перетащите аккаунты для настройки порядка отображения (опционально)
• Обновите квоту (Accounts → Обновить все квоты)
• Проверьте уровень подписки и квоту аккаунтов

Предупреждения о типичных ошибках

❌ Ошибка 1: Неправильное понимание 429 как "у модели нет емкости"

Симптом: При виде ошибки 429 думаешь, что у модели нет емкости.

Правильное понимание:

• 429 - это ограничение скорости, а не проблема емкости
• Добавление аккаунтов может снизить вероятность 429
• Изменение режима планирования может ускорить переключение

❌ Ошибка 2: Порог защиты квоты установлен слишком высоко

Симптом: Квота достаточна, но система постоянно пропускает аккаунты.

Причина: Защита квоты добавит модели ниже порога в protected_models аккаунта, прокси при планировании пропустит "защищенные модели". При слишком высоком пороге доступные аккаунты могут быть чрезмерно исключены.

Исправление:

• Вернитесь в Settings → Quota Protection, настройте модели мониторинга и пороги
• Если вы хотите точно знать, какие модели защищены, посмотрите protected_models в данных аккаунтов

❌ Ошибка 3: Режим фиксированного аккаунта блокирует ротацию

Симптом: Установлен Preferred Account, но после ограничения скорости этого аккаунта система "застряла".

Причина: В режиме фиксированного аккаунта система сначала использует указанный аккаунт, только когда аккаунт недоступен, понижается до round-robin.

Исправление:

• Если вам не нужен фиксированный аккаунт, очистите Preferred Account
• Или убедитесь, что квота фиксированного аккаунта достаточна, избегайте ограничения скорости

Контрольная точка ✅

• [ ] Можете различить исчерпание квоты и ограничение скорости апстрима
• [ ] Знаете, как просмотреть детали ошибки 429 в Proxy Monitor
• [ ] Понимаете разницу между тремя режимами планирования и сценариями использования
• [ ] Знаете, как проверить, нормально ли работает ротация аккаунтов
• [ ] Можете оптимизировать приоритет аккаунтов и проверить стратегию защиты квоты

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

Вопрос 1: Почему у меня несколько аккаунтов, но все равно возникает 429?

A: Возможные причины:

1. Все аккаунты одновременно вызывают ограничение скорости (слишком высокая частота запросов)
2. Последовательные запросы в режиме "повторного использования окна 60s" многократно используют один и тот же аккаунт, проще довести один аккаунт до ограничения скорости
3. Защита квоты ошибочно исключает доступные аккаунты
4. Общее количество аккаунтов недостаточно для вашей частоты запросов

Решение:

• Добавьте больше аккаунтов
• Используйте режим PerformanceFirst
• Проверьте, добавила ли Quota Protection используемые вами модели в protected_models (при необходимости настройте модели мониторинга и пороги)
• Снизьте частоту запросов

Вопрос 2: Будет ли ошибка 429 автоматически повторена?

A: Она будет автоматически повторена в рамках одного запроса. Максимальное количество повторных попыток обычно 3, конкретный метод расчета: min(3, размер пула аккаунтов), и минимум 1 попытка.

Пример количества повторных попыток:

• Пул аккаунтов с 1 аккаунтом → 1 попытка (без повторной попытки)
• Пул аккаунтов с 2 аккаунтами → 2 попытки (1 повторная попытка)
• Пул аккаунтов с 3 или более аккаунтами → 3 попытки (2 повторные попытки)

Общий процесс:

1. Записать информацию об ограничении скорости/перегрузке (попасть в RateLimitTracker)
2. Если можно разобрать время ожидания (например, RetryInfo.retryDelay / quotaResetDelay), сначала подождет короткое время, затем продолжит
3. При повторной попытке принудительно ротировать аккаунты (когда attempt > 0, force_rotate=true), попробовать использовать следующий доступный аккаунт для отправки запроса апстриму

Если все попытки неудачны, прокси вернет ошибку клиенту; в то же время вы все равно можете увидеть фактически использованные аккаунты из заголовков ответа (например, X-Account-Email) или Proxy Monitor.

Вопрос 3: Как просмотреть, как долго аккаунт ограничен?

A: Есть два способа:

Способ 1: Просмотрите логи, найдите rate-limited

🔒 [FIX #820] Preferred account xxx@gmail.com is rate-limited, falling back to round-robin

Способ 2: В логах будет показано оставшееся время ожидания

All accounts are currently limited. Please wait 30s.

Вопрос 4: Защита квоты и ограничение скорости - это одно и то же?

A: Нет.

Характеристика	Защита квоты	Отслеживание ограничения скорости
Условие срабатывания	Квота модели ниже порога	Получена ошибка 429
Область действия	Определенные модели	Весь аккаунт
Продолжительность	До восстановления квоты	Решает апстрим (обычно несколько секунд до нескольких минут)
Поведение	Пропустить эту модель	Пропустить этот аккаунт

Вопрос 5: Как принудительно сразу переключить аккаунт?

A: Можно подойти с точки зрения "сделать следующий запрос легче переключить аккаунт":

1. На уровне планирования: переключитесь на PerformanceFirst, пропустите липкие сессии и повторное использование окна 60s
2. Фиксированный аккаунт: если включен Preferred Account, сначала очистите его, иначе будет преимущественно использовать фиксированный аккаунт (пока он не ограничен/защищен)
3. Пул аккаунтов: увеличьте количество аккаунтов, при ограничении одного аккаунта проще найти альтернативный аккаунт

В рамках одного запроса прокси сам принудительно ротирует при повторной попытке (attempt > 0 вызовет force_rotate=true), но количество повторных попыток ограничено.

Краткий итог урока

• 429 в Antigravity Tools - это сигнал "апстрим временно недоступен", может быть ограничением скорости, исчерпанием квоты, недостатком емкости модели и т.д.
• Прокси записывает время охлаждения и пытается ротировать аккаунты при повторной попытке в рамках одного запроса (но количество повторных попыток ограничено)
• Режим планирования, Quota Protection, количество аккаунтов влияют на вероятность возникновения 429 и скорость восстановления
• С помощью Proxy Monitor, заголовков ответа X-Account-Email и логов можно быстро найти проблему

Следующий урок预告

Следующий урок мы изучим 404/Несовместимость путей: Base URL, префикс /v1 и клиенты с "дублирующимися путями".

Вы узнаете:

• Как возникает самая распространенная ошибка интеграции (404)
• Различия в конкатенации base_url у разных клиентов
• Как быстро исправить проблему 404

---

Приложение: Справка по исходному коду

Нажмите, чтобы увидеть местоположение исходного кода

Обновлено: 2026-01-23

Функция	Путь к файлу	Строки
Разбор задержки повтора 429 (RetryInfo / quotaResetDelay)	src-tauri/src/proxy/upstream/retry.rs	38-67
Инструмент разбора Duration	src-tauri/src/proxy/upstream/retry.rs	11-35
Перечисление режимов планирования (CacheFirst/Balance/PerformanceFirst)	src-tauri/src/proxy/sticky_config.rs	3-12
Разбор причины ограничения скорости и стратегия охлаждения по умолчанию	src-tauri/src/proxy/rate_limit.rs	5-258
Определение константы MAX_RETRY_ATTEMPTS (OpenAI handler)	src-tauri/src/proxy/handlers/openai.rs	14
Расчет количества повторных попыток (max_attempts = min(MAX_RETRY_ATTEMPTS, pool_size))	src-tauri/src/proxy/handlers/openai.rs	830
OpenAI handler: при 429/5xx отметить ограничение скорости и повторить/ротировать	src-tauri/src/proxy/handlers/openai.rs	349-389
Приоритет сортировки аккаунтов (ULTRA > PRO > FREE + remaining_quota)	src-tauri/src/proxy/token_manager.rs	504-538
Повторное использование окна 60s + избегание ограничения скорости/защиты квоты	src-tauri/src/proxy/token_manager.rs	624-739
Точка входа записи ограничения скорости (mark_rate_limited)	src-tauri/src/proxy/token_manager.rs	1089-1113
Точное блокирование 429 / обновление квоты в реальном времени / стратегия понижения (mark_rate_limited_async)	src-tauri/src/proxy/token_manager.rs	1258-1417

Ключевые константы:

• MAX_RETRY_ATTEMPTS = 3: Максимальное количество повторных попыток в рамках одного запроса (OpenAI/Gemini handler)
• 60: Повторное использование окна 60s (включается только в режимах, отличных от PerformanceFirst)
• 5: Время ожидания получения токена (секунды)
• 300: Порог раннего обновления токена (секунды, 5 минут)

Ключевые функции:

• parse_retry_delay(): Извлечение задержки повтора из ответа об ошибке 429
• get_token_internal(): Основная логика выбора и ротации аккаунтов
• mark_rate_limited(): Пометить аккаунт как состояние ограничения скорости