Отказы и резервное переключение

Claude Fable 5 и Claude Opus 5 включают классификаторы безопасности, которые могут отклонить запрос. Когда это происходит, вы получаете обычный ответ, а не ошибку, с stop_reason: "refusal". Обычно вы всё ещё можете получить ответ, отправив тот же запрос другой модели Claude. Эта страница показывает, как распознать «refusal» (отказ) и как настроить такой повтор.

Читайте эту страницу, когда вы разрабатываете на Claude Fable 5 или Claude Opus 5 и хотите, чтобы отклонённые запросы автоматически переходили к другой модели. Она также применима, когда вы только что увидели "refusal" в ответе и хотите знать, что делать дальше.

Связанные страницы:

• Причины остановки и резервное переключение: полный список значений stop_reason.
• Резервный кредит: как тарифицируются отклонённые запросы и как избежать двойной оплаты за кэширование подсказок при повторе.
• Промежуточное ПО SDK: вспомогательный компонент SDK, который оборачивает всё это.
• Cookbook по резервному переключению и тарификации: проработанный сквозной пример.

Самая простая настройка, в бета-версии на Claude API: установите fallbacks в значение "default", и API повторит отклонённый запрос на резервной модели («fallback» model), которую Anthropic рекомендует для его категории отказа. Для категорий без рекомендованной резервной модели отказ остаётся в силе.

client = Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    fallbacks="default",
    betas=["server-side-fallback-2026-07-01"],
)
print(response.model)

Следующие разделы описывают, что содержит ответ-отказ, когда использовать резервное переключение на стороне сервера или на стороне клиента и как каждое из них тарифицируется.



Как выглядит отказ

Отказ — это успешный ответ HTTP 200 с stop_reason: "refusal":

{
  "id": "msg_01XFUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-fable-5",
  "content": [],
  "stop_reason": "refusal",
  "stop_details": {
    "type": "refusal",
    "category": "cyber",
    "explanation": "This request was declined because it could enable cyber harm."
  },
  "usage": {
    "input_tokens": 412,
    "output_tokens": 0
  }
}

Объект stop_details объясняет отклонение:

• category: называет область политики, которая вызвала срабатывание классификатора.
• explanation: человекочитаемое описание. Текст не является стабильным, поэтому отображайте его, а не разбирайте.
• Оба поля равны null, когда отказ не соответствует именованной категории. Этот null — нормальное, постоянное значение, а не заполнитель.
• Сам stop_details равен null для любой причины остановки, кроме refusal.

Отказ может прийти до какого-либо вывода или в середине потока после частичного вывода. В любом случае рассматривайте любой частичный вывод как неполный и отбрасывайте его.



Выбор подхода к резервному переключению

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

Резервное переключение на стороне сервера и промежуточное ПО SDK применяют резервный кредит за вас. Страница Резервный кредит нужна вам только тогда, когда вы строите повтор самостоятельно.



Резервное переключение на стороне сервера

Резервное переключение на стороне сервера повторяет отклонённый запрос внутри одного вызова API. В режиме по умолчанию, когда основная модель отклоняет запрос и категория отказа имеет рекомендованную резервную модель, API выполняет тот же запрос на модели, которую Anthropic рекомендует для этой категории. Вместо этого вы можете указать до трёх собственных резервных моделей (ниже). В любом случае вы получаете один ответ, в котором указана ответившая модель, так что ваш пользователь получает ответ за один цикл обращения.



Выполнение запроса

Установите параметр fallbacks в строку "default" и отправьте бета-заголовок server-side-fallback-2026-07-01. Затем API применяет определённую на сервере маршрутизацию по умолчанию для запрошенной модели, которая выбирает рекомендованную резервную модель на основе категории отказа, сообщаемой классификатором, так что отклонённые запросы обслуживаются без необходимости поддерживать список моделей по мере изменения рекомендаций.

client = Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    fallbacks="default",
    betas=["server-side-fallback-2026-07-01"],
)

# Запись fallback_message в usage.iterations означает, что был запущен резервная модель;
# сопоставьте её со stop_reason, чтобы убедиться, что ответ был сформирован резервной моделью.
fallback_ran = any(
    iteration.type == "fallback_message"
    for iteration in response.usage.iterations or []
)
served_by_fallback = fallback_ran and response.stop_reason != "refusal"

print(
    json.dumps(
        {
            "stop_reason": response.stop_reason,
            "model": response.model,
            "served_by_fallback": served_by_fallback,
        }
    )
)

Anthropic устанавливает меры защиты для каждой модели индивидуально и для каждой категории политики в соответствии с возможностями модели: в зависимости от категории помеченный запрос может быть переключён на менее способную модель или отклонён. Режим "default" кодирует эти рекомендации для каждой модели и каждой категории за вас, так что отклонённый запрос повторяется на модели, которую Anthropic рекомендует для этой категории. Резервные переключения видны в любом случае: в ответе указана модель, которая его обслужила, а блок содержимого fallback отмечает передачу.

Маршрутизация применяется на стороне сервера и не публикуется для каждой модели в Models API. Чтобы увидеть, какая модель обслужила отклонённый запрос, проверьте поле model верхнего уровня в ответе и найдите запись fallback_message в usage.iterations, как это делают примеры на этой странице.

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



Указание собственных резервных моделей

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

client = Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    fallbacks=[{"model": "claude-opus-4-8"}],
    betas=["server-side-fallback-2026-07-01"],
)
print(response.model)

К списку fallbacks применяется несколько правил:

• Записи пробуются по порядку. Каждая должна отличаться от других записей и от запрошенной модели.
• Каждая запись должна быть одной из разрешённых целей запрошенной модели. С установленным бета-заголовком этот список публикуется как allowed_fallback_models в записи модели в Models API.
• Каждая запись называет model и может переопределить max_tokens, thinking, output_config и speed только для этой попытки.
• Запрос должен быть действительным как прямой запрос к каждой названной модели. Если резервная модель не поддерживает функцию, которую использует запрос, API отклоняет запрос сразу.
• Как и в режиме по умолчанию, только отклонение классификатором безопасности вызывает резервное переключение. Ограничение скорости, перегрузка или ошибка сервера на запрошенной модели возвращаются вам как есть.

Форма явного списка также работает с бета-заголовком server-side-fallback-2026-06-01; режим "default" — нет.

Ответ имеет одинаковую форму в обоих режимах: модель, обслужившая ход, появляется в поле model верхнего уровня, блок содержимого fallback отмечает передачу, а usage.iterations записывает каждую попытку.



Что содержит ответ

Ответ выглядит как любое другое сообщение, с двумя дополнениями:

• Поле model верхнего уровня сообщает модель, которая создала возвращённое сообщение, будь то запрошенная модель или резервная.
• Блок содержимого fallback отмечает каждую точку в content, где вывод одной модели уступает место следующей: {"type": "fallback", "from": {"model": ...}, "to": {"model": ...}}.
  • from.model повторяет строку модели, которую вы отправили, когда отклоняющим звеном является запрошенная модель.
  • to.model — это всегда разрешённый идентификатор модели, которая продолжает работу.

При отказе до какого-либо вывода блок fallback является первым блоком содержимого. Например, когда маршрутизация по умолчанию выбирает Claude Opus 4.8 для категории отказа:

{
  "id": "msg_01XFUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-4-8",
  "content": [
    {
      "type": "fallback",
      "from": { "model": "claude-fable-5" },
      "to": { "model": "claude-opus-4-8" }
    },
    { "type": "text", "text": "Hi! How can I help you today?" }
  ],
  "stop_reason": "end_turn",
  "stop_details": null,
  "usage": {
    "input_tokens": 412,
    "output_tokens": 264,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "iterations": [
      {
        "type": "message",
        "model": "claude-fable-5",
        "input_tokens": 535,
        "output_tokens": 0,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0
      },
      {
        "type": "fallback_message",
        "model": "claude-opus-4-8",
        "input_tokens": 412,
        "output_tokens": 264,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0
      }
    ]
  }
}

Массив usage.iterations записывает каждую попытку. Модель, которая отклонила запрос, появляется как обычная запись message, а модель, обслужившая ход, появляется как запись fallback_message. Если каждая модель в цепочке отклоняет запрос, ответом является отказ последней модели с записью message для каждого более раннего звена и записью fallback_message для последнего.



Продолжение разговора

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



Потоковая передача

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

Когда отклонение происходит до какого-либо вывода:

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

Когда отклонение происходит в середине вывода:

• Открытый блок содержимого закрывается, и блок fallback (обычная пара content_block_start и content_block_stop без дельт) отмечает границу.
• Резервная модель продолжает с частичного вывода. Только блоки text частичного вывода передаются резервной модели в качестве контекста; другие типы блоков остаются в content.
• message_start уже назвал запрошенную модель, поэтому считывайте обслуживающую модель из to.model блока fallback и из записи fallback_message в usage.iterations финального message_delta.



Непотоковые ответы

При непотоковом запросе отклонение в середине вывода ведёт себя иначе: ответ опускает частичный вывод отклонённой модели, и резервная модель отвечает с нуля. Результат выглядит как отклонение до какого-либо вывода, где блок fallback идёт первым. Отклонённая попытка и её выходные токены всё равно появляются в usage.iterations.



Резервное переключение на стороне клиента с промежуточным ПО SDK

Каждый SDK Anthropic включает «middleware» (промежуточное ПО) для резервного переключения при отказах. Вы настраиваете его один раз на клиенте со своим списком резервных моделей. Вызовы через client.beta.messages затем автоматически повторяют отклонённые запросы на любой платформе. Промежуточное ПО также отправляет бета-заголовок fallback-credit-2026-07-01 с каждым обрабатываемым запросом, поэтому повторы переоцениваются без настройки для каждого запроса.



Настройка

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

from anthropic import Anthropic, BetaFallbackState, BetaRefusalFallbackMiddleware

# При отказе middleware повторяет запрос на указанной резервной модели и
# автоматически отправляет бета-заголовок fallback-credit в каждом обрабатываемом запросе.
client = Anthropic(
    middleware=[BetaRefusalFallbackMiddleware([{"model": "claude-opus-4-8"}])],
)

state = BetaFallbackState()  # pins follow-ups to the model that accepted

# Потоковая передача: при отказе middleware повторяет запрос на резервной модели и
# вставляет её события в открытый поток.
with (
    state,
    client.beta.messages.stream(
        max_tokens=1024,
        model="claude-fable-5",
        messages=[{"role": "user", "content": "Hello, Claude"}],
    ) as stream,
):
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final_message = stream.get_final_message()
print(f"\nserved by: {final_message.model}")

# Без потоковой передачи: повторное использование состояния сохраняет привязку диалога.
with state:
    message = client.beta.messages.create(
        max_tokens=1024,
        model="claude-fable-5",
        messages=[{"role": "user", "content": "Hello, Claude"}],
    )
print(f"served by: {message.model}")



Как оно себя ведёт

• Повторы проходят по вашему списку резервных моделей по порядку. Резервная модель, которая сама отказывает, передаёт запрос следующей записи.
• Когда каждая модель в списке отклонила запрос, промежуточное ПО возвращает финальный отказ (ответ-отказ последней модели), а не вызывает ошибку.
• Блоки мышления от Claude Fable 5 проходят без изменений: каждый повтор повторно отправляет ваше исходное тело запроса, и единственные блоки, которые промежуточное ПО удаляет из истории разговора в последующих запросах, — это граничные блоки fallback, которые оно само добавило.
• Ответы, обслуженные через промежуточное ПО, включают блок содержимого fallback на каждой границе моделей, так же как ответы резервного переключения на стороне сервера. Промежуточное ПО управляет этими блоками за вас в последующих запросах.
• Модель, которая приняла запрос, записывается в BetaFallbackState, поэтому последующие запросы, использующие это состояние, остаются закреплёнными за ней, а не обращаются снова к модели, которая отказала.



Отказы в Message Batches

Отклонённый запрос в Message Batch возвращается как result.type: "succeeded" с stop_reason: "refusal". Результаты пакетов несут тот же объект stop_details, что и синхронные ответы, поэтому вы можете обнаруживать отказы через stop_reason или stop_details.type. Одно отличие: отказы в пакетах не создают резервные кредиты, поэтому stop_details в результате пакета никогда не включает fallback_credit_token.

Резервное переключение на стороне сервера недоступно для пакетов (пакетный запрос, включающий fallbacks, создаёт результат с ошибкой для соответствующего элемента). Чтобы повторить отклонённые элементы пакета:

1. Соберите отклонённые элементы из результатов.
2. Удалите блоки мышления Claude Fable 5 из любых многоходовых историй.
3. Повторно отправьте их на резервной модели как новый пакет или как прямые запросы.



Распространённые ошибки

• Повторяйте на другой модели. Повторная отправка отклонённого запроса той же модели обычно приводит к ещё одному отказу. Направьте повтор на резервную модель.
• Планируйте бюджет повторов на запрос, а не на ход или сессию. Один ход может произвести несколько отказов, например агент плюс его субагенты.
• Настройте резервное переключение на каждом пути запроса. Обработчики повторов, ветви восстановления после ошибок и фоновые воркеры — всем им это нужно. Обработчик, который повторно выдаёт запрос без резервного переключения, теряет защиту именно на тех запросах, которым она, скорее всего, понадобится.
• Дайте вызовам субагентов их собственное резервное переключение. Параметр fallbacks не распространяется на вызовы моделей, выполняемые изнутри выполнения инструментов.
• Сделайте резервное переключение свойством запроса, а не окружающего состояния. Общий флаг, кэшированное значение конфигурации или глобальный переключатель могут рассинхронизироваться и незаметно оставить запрос без защиты. Когда вы не можете подтвердить, что резервное переключение активно, настройте его, а не предполагайте, что оно включено.
• Инструментируйте отказы как отдельный сигнал. Отказ — это HTTP 200, поэтому мониторинг, построенный на частоте ошибок или ответах 5xx, никогда его не увидит. Генерируйте одно событие на каждый отказ и одно на каждый ответ, обслуженный резервной моделью (запись fallback_message в usage.iterations отмечает последний), затем настройте оповещения на разрыв между двумя счётчиками.
• Ветвитесь по stop_reason или stop_details.type, а не по content или внутренним полям stop_details. Объект stop_details всегда присутствует при отказе, но его поля category и explanation могут быть null. Проверяйте stop_reason на равенство "refusal" напрямую.



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