Как настроить fallback при сбое API

После выполнения этой инструкции у вас будет рабочая схема fallback при сбое API: сначала ограниченные повторы на временных ошибках, затем запасной ответ или secondary endpoint, а также проверка срабатывания через telemetry и request IDs.

Короткий ответ: если вам нужен устойчивый вызов API, настраивайте его в таком порядке: retry на временные ошибки, затем fallback как последний шанс, затем обязательная наблюдаемость. По официальным источникам самый подробно задокументированный путь — через Polly и .NET; для AWS SDK, Gemini API и OpenAI есть важные отдельные оговорки.

• Время: зависит от вашего клиента и SDK; официальные источники это не фиксируют.
• Сложность: средний.
• Стоимость: зависит от вашего API, числа повторов и запасного провайдера; в доступных источниках цены не указаны.
• Что потребуется: доступ к клиентскому коду или слою оркестрации, логи или telemetry, тестовый endpoint или искусственно падающий сервис, понимание того, какие операции у вас идемпотентны.
• Актуальные условия: инструкция собрана по официальным материалам, проверенным по source pack на 2026-08-15. Для Polly доступна стратегия fallback; в changelog на момент доступа верхняя запись — 8.7.0. Страницы .NET resilience помечены как обновлённые 2026-01-20 и 2026-02-24, страница Gemini troubleshooting — 2026-07-27 UTC. Для Grpc.Net.ClientFactory важна версия 2.64.0+; для нового поведения retry в AWS нужен opt-in через AWS_NEW_RETRIES_2026=true.

Редакционное ограничение: универсального официального рецепта для всех языков и всех API нет. Надёжнее всего документирован сценарий .NET/Polly; в остальных стеках вам придётся перенести тот же порядок действий в выбранный SDK или в слой оркестрации.

Что именно настраивать в разных стеках

Пошаговая настройка

1. Зафиксируйте, что именно считать временным сбоем.

   Сначала определите список ситуаций, на которых вообще допустимы retry и fallback. В Polly это выражается через ShouldHandle: стратегия fallback срабатывает, если операция завершилась исключением или неуспешным результатом. Для Gemini официальный источник отдельно называет временными случаями 429 RESOURCE_EXHAUSTED и 503 UNAVAILABLE; именно для них рекомендован exponential backoff.

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

2. Поставьте retries перед fallback.

   В документации Polly показан паттерн AddFallback(...).AddRetry(...). Логика здесь такая: fallback остаётся последним шансом, а повторы отрабатывают раньше. Это удобно, когда краткий сетевой сбой или кратковременный unavailable должен лечиться повтором, а не немедленным переключением на запасной ответ.

   Если вы используете HttpClient в .NET, Microsoft рекомендует AddHttpClient вместе с AddStandardResilienceHandler. Стандартный конвейер уже включает retry и circuit breaker; fallback нужно добавлять вокруг него как отдельную стратегию последнего шанса, а не вместо него.

   Ожидаемый результат: первичный вызов сначала проходит через ограниченные повторы, и только после исчерпания этих попыток управление переходит к fallback.

3. Настройте сам fallback как явное резервное поведение.

   В Polly fallback задаётся через FallbackStrategyOptions<T> и три ключевых элемента: ShouldHandle, FallbackAction и OnFallback. В FallbackAction вы либо возвращаете surrogate value, либо вызываете secondary endpoint. Это важно: fallback не должен быть «тихим провалом» с пустым значением, если ваш потребитель ждёт осмысленный ответ.

   Отдельная рекомендация из документации Polly: не бросайте исключения из OnFallback. Если вам нужно заменить или проанализировать поведение, Polly советует использовать ExecuteOutcomeAsync и разбирать Outcome или Exception, а не ломать телеметрию побочным исключением из обработчика.

   Ожидаемый результат: fallback у вас возвращает предсказуемый резервный ответ или переводит запрос на secondary endpoint, а срабатывание фиксируется отдельным событием.

4. Отключите повторы для небезопасных HTTP-методов, если они меняют состояние.

   Это критичный шаг для качества и безопасности. В .NET-статье про HTTP resilience прямо сказано, что стандартный обработчик по умолчанию применяет retries ко всем HTTP-методам, если вы отдельно не отключите unsafe methods. Для POST, PATCH, PUT, DELETE и CONNECT это может привести к повторной записи, двойной оплате или дублированию побочного эффекта.

   Если такие методы у вас не идемпотентны, используйте DisableForUnsafeHttpMethods() или эквивалентную настройку в вашем клиенте. Если у вас gRPC-клиент на базе Grpc.Net.ClientFactory, Microsoft отдельно предупреждает о совместимости и рекомендует версию 2.64.0+.

   Ожидаемый результат: ваши изменяющие запросы больше не попадают под автоматические повторы по умолчанию, а fallback не усиливает побочные эффекты.

5. Примените оговорки конкретного провайдера до боевого запуска.

   Для AWS встроенные retry в standard mode используют exponential backoff с jitter, но актуальное описание поведения требует opt-in через переменную AWS_NEW_RETRIES_2026=true, пока это не стало поведением по умолчанию. Для Gemini учитывайте, что официальные SDK уже умеют автоповторы, а Python SDK повторяет transient errors до четырёх раз; не дублируйте те же самые retry в нескольких слоях без необходимости.

   Для OpenAI важна трассировка: в production рекомендуется логировать x-request-id, а если ответ не пришёл из-за timeout или network issues, можно передавать собственный X-Client-Request-Id и связывать по нему клиентские логи с падением запроса.

   AWS_NEW_RETRIES_2026=true
   X-Client-Request-Id: req-2026-08-15-001
   x-request-id: <значение из ответа API>

   Ожидаемый результат: вы знаете, какие retry уже выполняет SDK, где нужен внешний fallback и как связать боевой инцидент с конкретным запросом.

6. Добавьте наблюдаемость и протестируйте схему на искусственно падающем сервисе.

   По Polly правильная проверка fallback — это telemetry-событие OnFallback. Для практической отладки используйте искусственно падающий endpoint или примеры из репозитория Polly-Samples, где есть демонстрации Fallback, Retry, CircuitBreaker и hedging. Ваша задача на этом шаге — не «посмотреть, что вроде бы работает», а получить подтверждение в логах, что сначала были retry, затем одно срабатывание fallback и затем осмысленный запасной ответ.

   Для OpenAI дополнительно убедитесь, что в логе рядом с событием сбоя есть либо x-request-id из ответа, либо ваш X-Client-Request-Id, если ответ не вернулся.

   Ожидаемый результат: у вас есть воспроизводимый тестовый сценарий, в котором резервный путь подтверждён телеметрией и идентификаторами запросов.

Как проверить, что всё работает

1. Сымитируйте временный сбой.

   Поднимите тестовый или staging endpoint, который отвечает ошибкой, timeout или недоступностью. Для .NET-пайплайнов можно опираться на примеры из Polly-Samples, где уже показаны связки Fallback и Retry.

2. Проверьте, что сначала отрабатывают retry.

   По логам и телеметрии убедитесь, что клиент делает ограниченное число повторов до срабатывания fallback. Если fallback включается сразу, значит порядок стратегий или условие обработки настроены неправильно.

3. Проверьте событие OnFallback.

   В успешной проверке это событие появляется только после исчерпания retry и ровно для тех ошибок, которые вы пометили как обрабатываемые.

4. Проверьте полезный результат fallback.

   Клиент должен получить либо surrogate value, либо ответ со secondary endpoint. Не принимайте за успех ситуацию, когда пользователь получил пустое значение без явного указания, что это резервный путь.

5. Проверьте трассировку запроса.

   Для OpenAI в логе должен быть x-request-id, а при timeout или network issues — ваш X-Client-Request-Id. Для AWS и Gemini зафиксируйте, какой слой сделал retry: SDK, ваш клиент или оркестратор.

Частые ошибки и исправления

• Ошибка: fallback срабатывает на слишком широком наборе ответов.
  Исправление: сузьте ShouldHandle до действительно временных ошибок. В Gemini официальный источник отдельно указывает backoff для 429 RESOURCE_EXHAUSTED и 503 UNAVAILABLE; не превращайте любой неуспех в повод для fallback.
• Ошибка: повторяются запросы, которые меняют состояние.
  Исправление: для стандартного .NET HTTP resilience отключите retry для unsafe methods через DisableForUnsafeHttpMethods(), если ваши POST, PATCH, PUT, DELETE или CONNECT не идемпотентны.
• Ошибка: вы не можете связать сбой с конкретным запросом.
  Исправление: логируйте x-request-id там, где ответ получен, и добавляйте свой X-Client-Request-Id для timeout и network issues, как рекомендует OpenAI.
• Ошибка: ожидаемое поведение AWS retry не включилось.
  Исправление: проверьте, что для вашего сценария действительно включён opt-in через AWS_NEW_RETRIES_2026=true, и перепроверьте поведение на версии конкретного SDK.
• Ошибка: вы бросаете исключение из OnFallback или пытаетесь менять через него основную логику.
  Исправление: не используйте OnFallback для такого поведения. Polly рекомендует не бросать из него исключения; если нужно анализировать исход выполнения, применяйте ExecuteOutcomeAsync и разбирайте Outcome или Exception.

Безопасность и ограничения

• Повторы и fallback увеличивают число вызовов. Это может поднять нагрузку на API и итоговые расходы. В доступных источниках нет цен и нет единой таблицы лимитов, поэтому стоимость и квоты проверяйте отдельно на product/pricing pages провайдеров.
• Небезопасные методы требуют отдельной защиты. Автоповторы для изменяющих запросов без явного контроля — частая причина дублирования записей и других побочных эффектов.
• Встроенные retry не равны полноценному fallback. У AWS SDK и Gemini есть документированные механизмы повторов на временных ошибках, но это не заменяет ваш резервный ответ или secondary endpoint.
• OpenAI не даёт здесь готовый движок fallback. Официальная страница покрывает отладку и request IDs. Если вам нужен переход на запасной маршрут, его нужно реализовать в клиентском коде или слое оркестрации.
• Официальное покрытие по языкам неравномерно. Практический вердикт: как эталон используйте паттерн Polly/.NET, а затем переносите его в ваш стек, не полагаясь на «магическое» единое поведение разных SDK.

Что делать дальше

• После fallback настройте rate limiting для API, чтобы ваши повторы не усугубляли ошибки 429.
• Если fallback переключает вас на другую модель или другого провайдера, добавьте guardrails для AI-приложения, чтобы не потерять контроль над качеством ответа.
• Если вы оркестрируете вызовы без собственного бэкенда, перенесите логику резервного пути в агента в n8n с ИИ или в AI-автоматизацию в n8n.
• Для более сложных маршрутов с несколькими ветками и условиями посмотрите, как это оформить через LangGraph для сложных workflows.

Источники

• Fallback resilience strategy | Polly
• Introduction to resilient app development – .NET | Microsoft Learn
• Build resilient HTTP apps: Key development patterns – .NET | Microsoft Learn
• Retry behavior – AWS SDKs and Tools
• Troubleshooting guide | Gemini API | Google AI for Developers
• API Overview | OpenAI API Reference
• GitHub – App-vNext/Polly-Samples
• Polly/CHANGELOG.md at main · App-vNext/Polly · GitHub

Вопросы и ответы

Можно ли ограничиться только retry без fallback?

Да, если вам достаточно переживать кратковременные сетевые или сервисные сбои. Fallback нужен, когда после исчерпания retry вы всё равно хотите вернуть запасной ответ или перейти на secondary endpoint.

Нужно ли включать fallback для POST и других изменяющих методов?

Только после проверки идемпотентности. Официальная .NET-документация отдельно предупреждает, что стандартный обработчик повторяет все HTTP-методы по умолчанию, если не отключить unsafe methods.

Есть ли у OpenAI готовый официальный механизм fallback?

В доступном официальном источнике — нет. Там описана отладка запросов и request IDs; сам fallback нужно реализовать в вашем клиенте или оркестрации.

Как понять, что сработал именно fallback, а не просто retry?

Ориентируйтесь на telemetry-событие OnFallback в Polly и на логи request IDs. В корректной схеме retry идут раньше, а OnFallback появляется только после их исчерпания.

Нужен ли внешний fallback, если AWS SDK или Gemini SDK уже умеют retry?

Часто да. Встроенные retry помогают на временных ошибках, но не заменяют запасной ответ, secondary endpoint или переключение на другой маршрут обработки.