Отказы и резервная модель

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

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

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

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

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

client = Anthropic()

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-06-01"],
)

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



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

Отказ — это успешный ответ 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. Вы указываете до трёх резервных моделей, и когда Claude Fable 5 отклоняет запрос, API запускает следующую модель в цепочке с тем же запросом. Вы получаете один ответ, в котором указана ответившая модель, так что ваш пользователь получает ответ за один цикл обмена.



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

Укажите резервные модели в параметре fallbacks и отправьте бета-заголовок server-side-fallback-2026-06-01.

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-06-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,
        }
    )
)

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

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



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

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

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

При отказе до какого-либо вывода блок fallback является первым блоком содержимого:

{
  "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 для TypeScript, Python, Go, Java и C# включают промежуточное ПО для резервного варианта при отказе. Вы настраиваете его один раз на клиенте со своим списком резервных моделей. Вызовы через client.beta.messages затем автоматически повторяют отклонённые запросы на любой платформе. Промежуточное ПО также отправляет бета-заголовок fallback-credit-2026-06-01 с каждым обрабатываемым запросом, так что повторные попытки переоцениваются без настройки для каждого запроса.



Настройка

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

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

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

# Потоковая передача: при отказе промежуточное ПО повторяет запрос на резервной модели и
# встраивает её события в открытый поток.
with (
    state,
    client.beta.messages.stream(
        max_tokens=1024,
        model="claude-fable-5",
        messages=[{"role": "user", "content": "Hello, Claude"}],
    ) as stream,
):
    for event in stream:
        if event.type == "text":
            print(event.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 на каждой границе моделей, так же как и ответы серверного резервного варианта. Промежуточное ПО управляет этими блоками за вас при последующих запросах.
• Модель, которая приняла запрос, записывается в BetaFallbackState, поэтому последующие запросы, использующие то же состояние, остаются закреплёнными за ней, а не повторно обращаются к модели, которая отказала.



Отказы в Message Batches

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

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

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



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

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



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