Claude API: как спроектировать безопасный fallback при отказе

Сначала определите, что именно отказало

Один код ответа не описывает весь контекст. Приложение должно различать локальную валидацию, отказ политики, временную сетевую проблему и timeout после отправки. Для каждого случая зафиксируйте только operation ID, версию адаптера, время и безопасную категорию. Это позволяет повторить проверку, не сохраняя prompt, токен, заголовок Authorization или чужие данные.

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

Не подменяйте бизнес-действие новым запросом

Fallback для текста, черновика или подсказки может быть менее рискованным, чем fallback для письма, заказа, прав доступа или публикации. До интеграции опишите границу side effect: что можно сформировать заново, а что требует подтверждения человека или безопасной сверки. Модельный ответ и транспортная ошибка не являются разрешением менять эту границу.

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

Сделайте состояние пользователя частью контракта

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

Состояние хранится в приложении вместе с idempotency key или локальным operation ID. При повторном открытии экрана сервер сначала читает эту запись, а не делает новый вызов. Если срок ожидания закончился, покажите действие «проверить статус» или «обратиться к оператору», а не кнопку, которая создаёт новый побочный эффект по умолчанию.

Ограничьте автоматический retry

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

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

Оставьте управляемую очередь сверки

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

Очередь не означает бесконечное хранение. Задайте владельца, срок и правило закрытия: подтверждённый успех, подтверждённый отказ или отмена после проверки. Если данных недостаточно, зафиксируйте unknown_outcome, а не сочиняйте техническую причину. Так fallback остаётся наблюдаемым процессом, а не скрытой заменой поведения.

Проверьте сценарий на синтетических fixtures

Регрессионный набор должен включать явный отказ, локальную ошибку формы, timeout до ответа, повторную доставку, устаревший результат и другой tenant. Каждый тест проверяет, что приложение не раскрывает секреты, не выполняет второй side effect и возвращает ожидаемое локальное состояние. Эти проверки можно запустить без сети и без реального ключа.

Продолжите с обработкой stop reason, правилами fallback моделей и локальным idempotency key. Перед production подтвердите текущий контракт выбранного маршрута и правила своего продукта.

Безопасный server-side пример

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

export function chooseFallback(operation) {
  if (!operation?.id || operation.status === 'unknown_outcome') {
    return { action: 'reconcile', userState: 'needs_review' };
  }
  if (operation.status === 'rejected_by_validation') {
    return { action: 'stop', userState: 'not_sent' };
  }
  return operation.idempotent === true
    ? { action: 'retry_once', userState: 'retrying' }
    : { action: 'stop', userState: 'needs_review' };
}

Критерий готовности

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

Граница ответственности и данных

Не передавайте в браузер, обычный журнал, тикет или статью API-ключи, заголовок Authorization, cookie, ключи поставщиков, полный prompt либо персональные данные. Для расследования используйте минимальные технические метаданные и синтетические fixtures.

Контроль перед выпуском

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

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

Полезные материалы

Anthropic error handling documentation · Google SRE: handling overload

FAQ

Нужно ли повторять запрос после timeout?

Не автоматически. Timeout не доказывает отсутствие результата. Сначала найдите локальную операцию, покажите неизвестный итог и выполните безопасную сверку. Retry допустим только для заранее определённого идемпотентного участка с конечным бюджетом.

Можно ли незаметно сменить маршрут?

Нет. Другой маршрут меняет контракт и риски. Оформите его как отдельный адаптер, повторно проверьте вход, права tenant и локальную авторизацию, а для заметного действия запросите подтверждение или направьте операцию на проверку.

Что должен видеть оператор?

Минимальные метаданные: локальный ID, tenant, категория состояния, версия адаптера, время и история переходов. Не передавайте полный prompt, токены, Authorization, cookie или исходные ответы в обычную очередь поддержки.

Следующий шаг

Продолжите с материалами: Обработка Claude API stop reason · Правила fallback моделей · Idempotency key при повторе. Затем протестируйте интеграцию на staging до production-трафика.