Claude Platform Docs
MessagesClaude로 빌드하기

폴백 크레딧

거부된 요청을 다른 모델에서 재시도할 때 프롬프트 캐시 비용을 두 번 지불하지 않도록 합니다.

프롬프트 캐시는 모델별로 존재합니다. 한 모델이 요청을 거부하여 다른 모델에서 재시도하면, 첫 번째 모델에 대해 이미 캐시된 대화 접두사(prefix)를 새 모델의 캐시에 처음부터 다시 써야 합니다. 캐시 쓰기는 캐시 읽기보다 비용이 더 많이 듭니다. "Fallback credit"(폴백 크레딧)은 이 추가 비용을 없애 줍니다. 거부 응답에는 크레딧 토큰이 포함되며, 재시도 시 이 토큰을 그대로 전달하면 재시도는 대화가 처음부터 새 모델에서 진행된 것처럼 청구됩니다.

이 페이지는 원시 HTTP를 사용하거나 사용자 정의 재시도 로직으로 재시도를 직접 구현하는 경우에만 필요합니다. 서버 측 폴백과 SDK 미들웨어는 폴백 크레딧을 자동으로 적용합니다. 둘 중 하나를 사용한다면 이 페이지는 건너뛰세요.

거부와 폴백에서는 거부를 감지하고 폴백 방식을 선택하는 방법을 다룹니다. 캐시 읽기와 캐시 쓰기라는 용어가 생소하다면 프롬프트 캐싱에서 설명을 확인하세요.

기본 흐름

  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: 크레딧을 나타내는 불투명(opaque) 문자열입니다.
    • fallback_has_prefill_claim: 어떤 재시도 본문 형태를 사용해야 하는지 알려 주는 불리언 값입니다.

    해당 거부에 사용할 수 있는 크레딧이 없으면 두 필드 모두 null입니다.

  3. 재시도 구성하기

    거부된 요청 본문에서 시작하세요. model을 폴백 모델로 설정하고 토큰을 최상위 fallback_credit_token 파라미터로 추가하세요. 아래 표에서 본문 형태를 선택하세요.

  4. 동일한 헤더로 재시도 보내기

    동일한 fallback-credit-2026-07-01 베타 헤더와 함께 재시도를 보내세요. 재시도에서 토큰을 사용(redeem)하려면 이 헤더가 필요합니다.

fallback_has_prefill_claim 필드는 재시도가 처음부터 다시 시작하는 대신 거부한 모델의 부분 출력을 이어서 계속할 수 있는지 알려 줍니다:

fallback_has_prefill_claim재시도 본문
true거부된 요청 본문을 변경 없이 그대로 사용하고, 거부 응답의 content를 그대로 담은 content를 가진 assistant 메시지 하나를 끝에 추가합니다. 재시도 모델은 거부한 모델이 멈춘 지점부터 응답을 이어 가며, 완료된 서버 도구 호출은 다시 실행되지 않습니다.
false거부된 요청 본문을 변경 없이 그대로 사용합니다.

예시

다음 예시는 거부될 수 있는 요청을 보내고, Claude Opus 4.8에 대한 재시도에서 크레딧 토큰을 사용합니다. 재시도 시도가 거절되면, 예시는 거절 단계(rejection ladder), 즉 재시도가 거절될 때에서 다루는 점점 더 단순해지는 재시도 형태의 순서를 따라 단계적으로 내려갑니다.

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가 아니면 continuation 형태를 우선 사용합니다
    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, 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는 같은 양만큼 더 높습니다. 변화량이 0이라면 토큰은 인정되었지만 재산정할 것이 없었다는 뜻입니다. 예를 들어 재시도 모델의 캐시가 이미 워밍되어 있었던 경우가 그렇습니다.

재시도가 거절될 때

대부분의 재시도는 첫 시도에서 토큰 사용에 성공합니다. 그렇지 않은 경우, API는 다음에 무엇을 시도해야 하는지 알려 주는 400 오류를 반환합니다.

  1. 이어 쓰기 거절됨: 변경 없는 본문을 다시 보내기

    assistant 메시지를 추가한 재시도가 400 오류로 거절되면, 거부된 요청 본문을 변경 없이, 여전히 토큰과 함께 다시 보내세요.

  2. 토큰 거절됨: 토큰 제거하기

    변경 없는 본문도 메시지에 fallback_credit_token이 언급된 400 오류로 거절되면, 토큰 없이 재시도하세요. 크레딧은 소멸되지만 재시도 자체는 처리됩니다.

참조

다음 섹션에서는 예외적인 경우와 전체 토큰 사용 규칙을 다룹니다. 대부분의 통합에서는 필요하지 않습니다.

다음 단계

거부와 폴백

거부를 감지하고 서버 측 폴백, SDK 미들웨어, 수동 재시도 중에서 선택하세요.

프롬프트 캐싱

캐시 읽기와 캐시 쓰기가 청구되는 방식.

중지 이유와 폴백

모든 stop_reason 값과 각각을 처리하는 방법.

SDK 미들웨어

폴백 크레딧을 자동으로 적용하는 SDK 헬퍼.

Was this page helpful?