Надёжность интеграции

Ошибка 429 API: как настроить retry и backoff для AI-приложения

Ошибка 429 — не сигнал «нажать ещё раз быстрее». Она сообщает, что сервис временно не принимает текущий поток запросов по действующему лимиту. Для AI-приложения корректная реакция состоит из диагностики, ограниченных повторов, очереди и прозрачного ответа пользователю. Так система становится устойчивее и не превращает краткий лимит в лавину повторов.

Опубликовано 6 августа 2026 · 10 минут чтения · Ключевой запрос: ошибка 429 API

Что именно означает 429

HTTP 429 обычно называется Too Many Requests. На практике за ним могут стоять разные ограничения: слишком много запросов за короткий промежуток, слишком большой одновременный поток, исчерпанная квота ключа или временное правило выбранного маршрута. Код сам по себе не отвечает на вопрос «когда можно повторить». Поэтому приложение должно записать безопасные технические данные — код, тип ошибки, request ID при наличии и время попытки — и проанализировать тело ответа или документированные заголовки. Авторизацию и пользовательский текст в эти записи не включают.

429 следует отличать от ошибок, которые не лечатся ожиданием. Неверный JSON, несуществующая модель, отсутствие прав или некорректный ключ относятся к конфигурации запроса. Бессмысленный retry в этих случаях только создаст лишний трафик. Аналогично 5xx может быть временным сбоем, но его политика повторов должна быть отдельной и ещё более осторожной. Прежде чем писать обработчик, договоритесь в команде, какие статусы являются повторяемыми, сколько времени пользователь готов ждать и какая операция безопасна для повторной отправки.

Почему мгновенный retry ухудшает ситуацию

Если десять воркеров получили 429 и одновременно отправили одинаковый запрос через секунду, они создают новый пик. Если они повторяют снова через секунду, пик становится периодическим. Такая «стадная» нагрузка мешает и вашему приложению, и другим пользователям лимита. На стороне пользователя это выглядит как бесконечный индикатор, а в метриках — как лавинообразный рост ошибок.

Практичная альтернатива — exponential backoff: между попытками ожидание растёт, например 1, 2, 4 секунды, а к нему добавляется случайное небольшое отклонение, jitter. Jitter нужен, чтобы похожие запросы не просыпались в один момент. Если ответ содержит надёжное указание времени ожидания и вы уверены, что оно применимо к этому endpoint, его можно предпочесть собственной формуле. Всегда ставьте верхнюю границу ожидания и общее число попыток.

Минимальная политика повторов

Ниже приведён самостоятельный пример на JavaScript для серверного окружения с fetch. Он не содержит рабочего ключа. Пример предполагает, что RUSSIAAPI_API_KEY и RUSSIAAPI_MODEL заданы в защищённом окружении сервера, а модель подтверждена командой GET /v1/models. Он намеренно ограничен тремя попытками и не предназначен для запуска в браузере.

const baseUrl = 'https://russiaapi.com/v1';
const maxAttempts = 3;

function sleep(ms) { return new Promise(resolve => setTimeout(resolve, ms)); }

async function createCompletion(messages) {
  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
    const response = await fetch(`${baseUrl}/chat/completions`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.RUSSIAAPI_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ model: process.env.RUSSIAAPI_MODEL, messages })
    });
    if (response.ok) return response.json();
    if (response.status !== 429 || attempt === maxAttempts - 1) {
      throw new Error(`AI request failed with HTTP ${response.status}`);
    }
    const jitterMs = Math.floor(Math.random() * 250);
    await sleep((1000 * 2 ** attempt) + jitterMs);
  }
}

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

Ограничивайте параллелизм до отправки

Повторы работают после лимита; очередь и ограничение конкурентности уменьшают вероятность попасть в него. Вместо того чтобы выпускать все запросы из веб-сервера сразу, пропускайте их через пул с понятным числом одновременных задач. Размер пула не выбирают «на глаз»: начните консервативно, измерьте задержки и долю 429, затем меняйте значение небольшими шагами. Для разных функций продукта — чат, пакетная обработка, фоновые отчёты — полезны отдельные очереди, чтобы тяжёлый batch не вытеснял интерактивных пользователей.

Также ограничивайте входные данные до обращения к модели. Максимальная длина сообщения, число вложенных документов, лимит токенов ответа и дедупликация одинаковых задач одновременно снижают расход и нагрузку. Эта же дисциплина помогает бюджету; подробный разбор есть в статье о стоимости LLM API. Не путайте снижение параллелизма с попыткой обойти правила: цель — уважать допустимые границы сервиса и дать пользователю предсказуемый результат.

Какие метрики помогут найти причину

Одна цифра «429 за день» почти ничего не объясняет. Полезнее видеть долю 429 по endpoint, модели, ключу приложения и типу задачи, не раскрывая секреты. Добавьте длительность очереди, число попыток, время до успешного ответа, отмены пользователем и окончательные ошибки. Если после релиза растёт именно очередь, возможно, приложение отправляет больше работ, чем может обработать. Если 429 возникают только у одного ключа, проверьте его квоты и потребителей.

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

Порядок разбора инцидента

1. Зафиксируйте время, endpoint, модель и request ID, исключив секреты и персональные данные.
2. Проверьте, не изменился ли параллелизм, размер очереди, релиз клиента или входной поток.
3. Сверьте права и лимиты собственного ключа в консоли; не меняйте его на чужой.
4. Уменьшите нагрузку, включите ограниченные повторы с jitter и сообщите пользователям реальный статус.
5. После стабилизации обновите лимиты, алерты и тесты, чтобы причина не вернулась незаметно.

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

FAQ

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

• OpenAI-совместимый API: безопасное подключение
• Как снизить стоимость LLM API
• Документы RussiaAPI
• Каталог моделей и доступность