Claude Platform Docs
СообщенияРазработка с Claude

Кредит при резервном переключении

Избегайте двойной оплаты стоимости кэша подсказок при повторной отправке отклонённого запроса на другую модель.

Кэши подсказок привязаны к конкретной модели. Когда модель отклоняет запрос и вы повторяете его на другой модели, префикс диалога, уже закэшированный для первой модели, должен быть полностью записан в кэш новой модели. Запись в кэш стоит дороже, чем чтение из кэша. «Fallback credit» (кредит при резервном переключении) устраняет эти дополнительные расходы. Отказ содержит токен кредита, вы передаёте этот токен при повторной попытке, и повторная попытка оплачивается так, как если бы диалог с самого начала вёлся на новой модели.

Эта страница нужна вам, только если вы реализуете повторную попытку самостоятельно: через чистый HTTP или с собственной логикой повторных попыток. Резервное переключение на стороне сервера и клиентская резервная обработка с промежуточным ПО SDK применяют кредит при резервном переключении автоматически. Если вы используете любой из этих вариантов, пропустите эту страницу.

Страница Отказы и резервное переключение описывает обнаружение отказов и выбор подхода к резервному переключению. Страница Кэширование подсказок объясняет, что такое «cache reads» (чтение из кэша) и «cache writes» (запись в кэш), если эти термины вам незнакомы.

Базовый процесс

  1. Подключитесь с помощью бета-заголовка

    Отправьте запрос, который может быть отклонён, с заголовком anthropic-beta: fallback-credit-2026-07-01. Заголовок server-side-fallback-2026-07-01 также предоставляет те же поля, за исключением Claude Models on Google Cloud (Google managed) и Amazon Bedrock, которые возвращают ошибку 400 для этого заголовка. Заголовок fallback-credit-2026-06-01 принимается и предоставляет те же поля.

  2. Прочитайте два поля из отказа

    При отказе stop_details содержит два поля:

    • fallback_credit_token: непрозрачная строка, представляющая кредит
    • fallback_has_prefill_claim: логическое значение, указывающее, какую форму тела повторного запроса использовать

    Оба поля равны null, когда для данного отказа кредит недоступен.

  3. Сформируйте повторный запрос

    Начните с тела отклонённого запроса. Установите model в резервную модель и добавьте токен как параметр верхнего уровня fallback_credit_token. Выберите форму тела из следующей таблицы.

  4. Отправьте повторный запрос с тем же заголовком

    Отправьте повторный запрос с тем же бета-заголовком fallback-credit-2026-07-01. Заголовок необходим повторному запросу для погашения токена.

Поле fallback_has_prefill_claim сообщает, может ли повторный запрос продолжить частичный вывод отказавшей модели вместо того, чтобы начинать заново:

fallback_has_prefill_claimТело повторного запроса
trueТело отклонённого запроса без изменений плюс одно добавленное в конец сообщение ассистента, content которого повторяет content отклонённого ответа. Модель повторной попытки продолжает ответ с того места, где остановилась отклонившая модель, а завершённые вызовы серверных инструментов повторно не выполняются.
falseТело отклонённого запроса без изменений.

Пример

В следующем примере выполняется запрос, который может быть отклонён, и токен кредита погашается при повторной попытке с Claude Opus 4.8. Когда повторная попытка отклоняется, пример последовательно спускается по «лестнице отклонений»: последовательности всё более простых форм повторного запроса, описанной в разделе Когда повторный запрос отклонён.

client = Anthropic()

request = {
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello, Claude"}],
}


def send(model: str, body: dict[str, object]) -> BetaMessage:
    return client.beta.messages.create(
        model=model, betas=["fallback-credit-2026-07-01"], **body
    )


response = send("claude-fable-5", request)

if (
    response.stop_reason == "refusal"
    and (details := response.stop_details)
    and (token := details.fallback_credit_token)
):
    exact_body = request | {"fallback_credit_token": token}
    # Предпочитать форму продолжения, если claim не равен False
    if details.fallback_has_prefill_claim is not False:
        echoed = [block.model_dump() for block in response.content]
        match echoed:
            case [*_, {"type": "text"} as final_block]:
                final_block["text"] = final_block["text"].rstrip()
        attempt = exact_body | {
            "messages": [
                *request["messages"],
                {"role": "assistant", "content": echoed},
            ]
        }
    else:
        attempt = exact_body

    try:
        response = send("claude-opus-4-8", attempt)
    except BadRequestError as error:
        if "redemption temporarily unavailable" in error.message:
            raise  # Transient: retry with the token within its five-minute window
        try:
            # Откат к неизменённому телу, по-прежнему с токеном
            response = send("claude-opus-4-8", exact_body)
        except BadRequestError as retry_error:
            if "redemption temporarily unavailable" in retry_error.message:
                raise  # Transient: retry with the token within its five-minute window
            # Сам токен был отклонён: отказаться от него и повторить без него.
            response = send("claude-opus-4-8", request)

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

Где это работает

Кредит при резервном переключении находится в стадии бета-тестирования в Claude API, Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Google managed) и Microsoft Foundry. Отказы в Message Batches не создают токены кредита, а погашение применяется только к прямым запросам Messages API: токен, переданный в пакетном запросе, принимается, но игнорируется. Отказ Claude Haiku 5.5 не содержит кредита при резервном переключении, поэтому повторная попытка после него оплачивается по полной стоимости записи кэша подсказок резервной модели.

Резервная модель должна быть одной из разрешённых целей резервного переключения для отказавшей модели. Для Claude Fable 5.1, Claude Fable 5 и Claude Opus 5.5 это Claude Opus 4.8 (claude-opus-4-8) и Claude Opus 5 (claude-opus-5). Для Claude Opus 5 это Claude Opus 4.8. Для Claude Sonnet 5.5 это Claude Sonnet 5 (claude-sonnet-5).

Проверка применения кредита

Возврат виден в поле usage повторного запроса. По сравнению с тем, что тот же запрос показал бы без токена, значение cache_creation_input_tokens ниже, а cache_read_input_tokens выше на ту же величину. Нулевой сдвиг означает, что токен был принят, но переоценивать было нечего, например потому, что кэш резервной модели уже был «прогрет».

Когда повторный запрос отклонён

Большинство повторных запросов погашают токен с первой попытки. Если этого не происходит, API возвращает ошибку 400, которая подсказывает, что попробовать дальше.

  1. Продолжение отклонено: отправьте тело без изменений

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

  2. Токен отклонён: уберите токен

    Если тело без изменений также отклонено с ошибкой 400, в сообщении которой упоминается fallback_credit_token, повторите запрос без токена. Кредит теряется, но сам повторный запрос проходит.

Справочник

Следующие разделы описывают пограничные случаи и полные правила погашения. Большинству интеграций они не нужны.

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

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

Как тарифицируются чтение из кэша и запись в кэш.

Все значения stop_reason и способы их обработки.

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

Доступность

Кредит при резервном переключении находится в бета-версии для некоторых моделей.

Поддержка API

Использование

Нужен, только если вы сами реализуете повтор: отправьте бета-заголовок fallback-credit-2026-07-01 и передайте fallback_credit_token из отказа в повторном запросе.

СтатусБета
Облачные платформы
СтатусБета
Облачные платформы
В Amazon Bedrock и Google Cloud токен привязан к вашей идентичности вызывающей стороны (рабочих пространств нет), а allowed_fallback_models недоступен.
СтатусНедоступно

Обязательные бета-заголовки

Обзор бета-заголовков

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

Заголовок
  • fallback-credit-2026-07-01
  • илиserver-side-fallback-2026-07-01
  • илиfallback-credit-2026-06-01
Облачные платформы
Заголовок
  • fallback-credit-2026-07-01
  • илиfallback-credit-2026-06-01
Облачные платформы

Эта страница была полезной?