프롬프트 캐시는 모델별로 관리됩니다. Claude Fable 5가 요청을 거부하고 다른 모델에서 재시도하면, Claude Fable 5에 이미 캐시되어 있던 대화 접두사를 새 모델의 캐시에 처음부터 다시 기록해야 합니다. 캐시 쓰기는 캐시 읽기보다 비용이 더 많이 듭니다. "Fallback credit"(폴백 크레딧)은 이 추가 비용을 제거합니다. 거부 응답에 크레딧 토큰이 포함되어 있고, 재시도 시 이 토큰을 그대로 전달하면, 재시도는 처음부터 새 모델에서 대화가 진행된 것처럼 과금됩니다.
이 페이지는 원시 HTTP를 사용하거나 사용자 정의 재시도 로직으로 재시도를 직접 구축하는 경우에만 필요합니다. 서버 측 폴백과 SDK 미들웨어는 폴백 크레딧을 자동으로 적용합니다. 둘 중 하나를 사용한다면 이 페이지는 건너뛰어도 됩니다.
거부 및 폴백에서는 거부 감지와 폴백 접근 방식 선택을 다룹니다. 캐시 읽기와 캐시 쓰기라는 용어가 생소하다면 프롬프트 캐싱에서 설명을 확인하세요.
베타 헤더로 옵트인
거부될 수 있는 요청을 anthropic-beta: fallback-credit-2026-07-01 헤더와 함께 전송합니다. server-side-fallback-2026-07-01 헤더도 동일한 필드를 제공하며, 이전의 fallback-credit-2026-06-01 헤더도 계속 허용되고 동일한 필드를 제공합니다.
거부 응답에서 두 필드 읽기
거부 시 stop_details에는 두 개의 필드가 포함됩니다:
fallback_credit_token: 크레딧을 나타내는 불투명한 문자열입니다.fallback_has_prefill_claim: 어떤 재시도 본문 형태를 사용해야 하는지 알려주는 불리언 값입니다.해당 거부에 대해 사용할 수 있는 크레딧이 없으면 둘 다 null입니다.
재시도 구성
거부된 요청 본문에서 시작합니다. model을 폴백 모델로 설정하고 토큰을 최상위 fallback_credit_token 매개변수로 추가합니다. 아래 표에서 본문 형태를 선택하세요.
동일한 헤더로 재시도 전송
동일한 fallback-credit-2026-07-01 베타 헤더와 함께 재시도를 전송합니다. 토큰을 사용하려면 재시도에 이 헤더가 필요합니다.
fallback_has_prefill_claim 필드는 재시도가 처음부터 다시 시작하는 대신 거부된 모델의 부분 출력을 이어서 계속할 수 있는지 알려줍니다:
fallback_has_prefill_claim | 재시도 본문 |
|---|---|
true | 거부된 요청 본문을 변경하지 않고, 거부된 응답의 content를 그대로 담은 assistant 메시지 하나를 끝에 추가합니다. 재시도 모델은 거부된 모델이 멈춘 지점부터 응답을 이어가며, 완료된 서버 도구 호출은 다시 실행되지 않습니다. |
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가 아닌 한 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, AWS의 Claude Platform, Google Cloud, Microsoft Foundry에서 베타로 제공됩니다. Message Batches의 거부는 크레딧 토큰을 발급하지 않으며, 토큰 사용은 직접적인 Messages API 요청에만 적용됩니다. 배치 요청에 전달된 토큰은 허용되지만 무시됩니다.
재시도 모델은 거부된 모델의 허용된 폴백 대상 중 하나여야 합니다. 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 오류를 반환합니다.
이어쓰기 거절: 변경하지 않은 본문 재전송
assistant 메시지를 추가한 재시도가 400 오류로 거절되면, 거부된 요청 본문을 변경하지 않고 토큰과 함께 다시 전송합니다.
토큰 거절: 토큰 제거
변경하지 않은 본문도 fallback_credit_token을 언급하는 메시지와 함께 400 오류로 거절되면, 토큰 없이 재시도합니다. 크레딧은 소멸되지만 재시도 자체는 처리됩니다.
거부된 요청이 서버 도구를 실행했다면, 토큰 없는 재시도는 해당 도구를 다시 실행하고 다시 과금합니다. 이 경우 토큰 없는 재시도로 넘어가는 대신 400 오류를 호출자에게 표시하세요.
아래 섹션은 엣지 케이스와 전체 토큰 사용 규칙을 다룹니다. 대부분의 통합에는 필요하지 않습니다.
거부를 감지하고 서버 측 폴백, SDK 미들웨어, 수동 재시도 중에서 선택합니다.
캐시 읽기와 캐시 쓰기가 과금되는 방식입니다.
모든 stop_reason 값과 처리 방법입니다.
폴백 크레딧을 자동으로 적용하는 SDK 헬퍼입니다.
Was this page helpful?