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

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

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

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

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

await client.beta.messages.create({
  model: "claude-fable-5",
  max_tokens: 1024,
  messages,
  betas: ["server-side-fallback-2026-06-01"],
  fallbacks: [{ model: "claude-opus-4-8" }]
});

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

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

Отказ — это успешный ответ 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.

К списку 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 для всех запросов разговора.

Как оно работает

• Повторные попытки проходят по вашему списку резервных моделей по порядку. Резервная модель, которая сама отказывает, передаёт запрос следующей записи.
• Исходный ответ с отказом возвращается только тогда, когда каждая модель в списке отклонила запрос. Промежуточное ПО не вызывает для этого ошибку.
• Блоки мышления от 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 в отмечает последнее), затем настройте оповещение на разрыв между двумя счётчиками.

Дальнейшие шаги