Последние
Разработка

Ошибки 429 и 503 в API ИИ: как повторять запросы без лавины и дублей

Коды 429 и 503 часто допускают повтор, но не любой и не бесконечный. Надёжный обработчик сначала читает причину и Retry-After, затем применяет единый бюджет попыток, backoff с jitter и защиту от повторного побочного эффекта.

В этом материале7 разделов
Схема обработки ошибок API: определить 429 или 503, выдержать Retry-After, ограничить повторы и защититься от дублей.
Редакционная схема PENROUZ NEWS. Повтор безопасен только с пределом времени и защитой от дублей.PENROUZ NEWS

Сообщить об ошибке или предложить уточнение

Короткий ответ: повторяйте только временную ошибку и только в пределах бюджета

Код 429 обычно сообщает об ограничении частоты или использования, а 503 — о временной недоступности сервиса. В API поставщиков причина уточняется телом ошибки: один и тот же класс ответа может требовать ожидания либо действия владельца. OpenAI и Claude описывают Retry-After как число секунд до допустимой следующей попытки, когда этот заголовок присутствует.

Однако одного кода недостаточно. У одного поставщика 429 может означать временное ограничение скорости, а может сопровождать исчерпанный баланс или установленный лимит расходов. В документации OpenAI эти причины разделяются по полю error.code: временный rate limit допускает повтор, а ошибки баланса и квоты требуют действия владельца. Поэтому правило «повторять любой 429» ошибочно.

Решение по ответу API

СигналЧто проверитьДействие
429 + временный rate limiterror.code, Retry-After, оставшийся общий срокДождаться не меньше Retry-After; без него — backoff с jitter
429 + баланс, квота или лимит расходовerror.code и настройки проектаНе повторять; вернуть задачу оператору или в отложенное состояние
503 + временная перегрузкаRetry-After и общий срок операцииПовторить после указанного ожидания; при продолжении увеличить задержку
4xx с постоянной причинойтело ошибки, параметры, авторизацияИсправить запрос или доступ, а не нагружать сервис повтором
Точные коды и поля ошибки сверяйте с документацией конкретного API; таблица показывает общий порядок решения.

Сначала выберите один слой, который отвечает за повторы

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

Определите одного владельца retry-политики. Для простого сервиса это может быть HTTP-клиент; для очереди с дедлайном — сама очередь, а встроенные повторы SDK тогда отключаются. В журнале сохраняйте номер попытки, HTTP-статус, безопасный код ошибки, рассчитанную задержку и остаток общего бюджета. Токены доступа, полный пользовательский ввод и персональные данные в такой журнал не помещайте.

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

Политика ожидания: Retry-After, backoff, jitter и общий дедлайн

Если сервер прислал корректный Retry-After, считайте его минимальной задержкой. Не заменяйте его более коротким локальным ожиданием. Если заголовка нет или значение нельзя разобрать, используйте экспоненциальное увеличение задержки: например, базовую паузу умножайте на степень двойки. Добавьте небольшую случайную составляющую — jitter, чтобы множество клиентов не проснулось одновременно.

Ограничьте одновременно число попыток и полное время операции. Лимит попыток защищает от бесконечного цикла, а дедлайн — от одного слишком длинного ожидания. Тайм-аут отдельного HTTP-запроса не равен дедлайну всей задачи: три запроса с тайм-аутом по двадцать секунд плюс ожидания легко выходят за минутный пользовательский предел.

Псевдокод единой retry-политики
deadline = now + operation_budget
for attempt in 1..max_attempts:
  response = send_once()
  if response.ok: return response
  reason = classify(status, error.code)
  if reason is permanent: stop_and_report()
  delay = valid_retry_after_or_backoff(attempt)
  delay = max(delay, retry_after) + random_jitter()
  if now + delay exceeds deadline: defer_or_fail()
  sleep(delay)
raise retry_budget_exhausted

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

Защита от дублей важнее самого повтора

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

Присвойте операции стабильный ключ на уровне приложения и храните её состояние: создана, выполняется, завершена, требует проверки. Перед повторной записью проверяйте этот ключ. Если конкретный API поддерживает idempotency key, следуйте его официальному контракту; не предполагайте поддержку по аналогии с другим поставщиком. Даже при таком заголовке локальная таблица состояния нужна для бизнес-действий после ответа модели.

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

Вымышленный пример: очередь «Север»

Представим вымышленную службу «Север», которая раз в минуту забирает обращения и просит модель присвоить им категорию. Каждая задача получает ключ вида ticket-1842-classify-v1. Владелец политики — очередь: SDK-повторы отключены, у операции есть четыре попытки и общий дедлайн, после которого задача возвращается в отложенное состояние.

При временном 429 очередь читает Retry-After, добавляет небольшой jitter и планирует следующую попытку. При 503 действует так же, но после исчерпания бюджета не продолжает цикл в рабочем процессе. При 429 с кодом, указывающим на баланс или лимит расходов, задача сразу помечается как требующая настройки проекта. Успешный ответ проходит проверку схемы и только затем записывается по ключу задачи; повторный ответ с тем же ключом не создаёт вторую запись.

Если приложение показывает ответ по мере генерации, отдельно проверьте завершение потока. Руководство про потоковые ответы API объясняет, почему полученные фрагменты нельзя считать готовым результатом до финального события.

Проверяемая последовательность тестирования

  1. Отключите реальные внешние действия и подмените HTTP-клиент управляемым тестовым сервером.
  2. Смоделируйте 429 с Retry-After и убедитесь, что повтор не случился раньше указанного времени.
  3. Смоделируйте 429 без заголовка и проверьте рост backoff, наличие jitter и предел попыток.
  4. Верните 429 с постоянной причиной и убедитесь, что цикл не запускается.
  5. Смоделируйте 503 до исчерпания дедлайна и после него; второй случай должен завершиться отложенным состоянием.
  6. Верните успех после тайм-аута первого клиента и убедитесь, что один ключ операции создаёт один побочный эффект.
  7. Включите встроенные повторы SDK в тестовой конфигурации и докажите по счётчику, что приложение учитывает или отключает их.
  8. Проверьте журнал: в нём должны быть решение и задержка, но не секреты и не полный закрытый ввод.

Минимальный набор сценариев

СценарийОжидаемый результатДоказательство
429 + Retry-Afterожидание не короче подсказкиметка времени двух попыток
429 без Retry-Afterbackoff с jitter и конечный лимитзаписанные задержки и число обращений
429 с постоянной причинойнемедленная остановкаодна попытка и код решения
503 до дедлайнаограниченный повторостаток бюджета после каждой попытки
успех после неопределённого исходаодин побочный эффектодна запись на operation_key
Это учебный шаблон проверки. Значения задержек задаются владельцем системы и условиями конкретного API.

После стабилизации запросов можно отдельно уменьшать повторяемую нагрузку. Материал про кэширование промптов показывает, как проверять cache hit и не смешивать экономию с корректностью retry-политики.

Чек-лист перед включением в рабочем контуре

Обработчик готов к ограниченному запуску, если он различает временные и постоянные причины, уважает Retry-After, имеет один владеющий слой, ограничивает попытки и общее время, предотвращает дубли и проверен на управляемых ошибках. Метрика успеха — не отсутствие всех 429 и 503, а предсказуемое завершение каждой операции без лавины повторов и скрытого повторного действия.

Прозрачность

Источники и примечания

  1. Rate limits | OpenAI API
  2. Error codes | OpenAI API
  3. Rate limits | Claude Platform Docs

В этом материале

На этом устройстве

Сохранённые материалы