Claude Platform Docs
MessagesРазработка с Claude

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

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

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

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

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

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

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

    Отправьте запрос, который может быть отклонён, с заголовком anthropic-beta: fallback-credit-2026-07-01. Заголовок server-side-fallback-2026-07-01 также предоставляет те же поля, а более ранний заголовок 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 на AWS, Google Cloud и Microsoft Foundry. Отказы в Message Batches не выпускают токены кредита, а погашение применяется только к прямым запросам Messages API: токен, переданный в пакетном запросе, принимается, но игнорируется.

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

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

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

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

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

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

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

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

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

Справочник

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

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

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

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

Кэширование подсказок

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

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

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

Промежуточное ПО SDK

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

Was this page helpful?