프롬프트 캐시는 모델별로 관리됩니다. Claude Fable 5가 요청을 거부하고 다른 모델에서 재시도할 경우, Claude Fable 5에 대해 이미 캐시된 대화 접두사를 새 모델의 캐시에 처음부터 다시 써야 합니다. 캐시 쓰기는 캐시 읽기보다 비용이 더 많이 듭니다. "Fallback credit"(폴백 크레딧)은 이러한 추가 비용을 제거합니다. 거부 응답에 크레딧 토큰이 포함되며, 재시도 시 해당 토큰을 그대로 전달하면 재시도는 대화가 처음부터 새 모델에서 진행된 것처럼 과금됩니다.
이 페이지는 재시도를 직접 구현하는 경우에만 필요합니다. 예를 들어 Ruby 또는 PHP SDK를 사용하거나, 원시 HTTP를 통해 호출하거나, 사용자 정의 재시도 로직을 사용하는 경우입니다. 서버 측 폴백과 SDK 미들웨어는 폴백 크레딧을 자동으로 적용합니다. 둘 중 하나를 사용한다면 이 페이지는 건너뛰세요.
거부 및 폴백에서는 거부를 감지하고 폴백 방식을 선택하는 방법을 다룹니다. 캐시 읽기와 캐시 쓰기라는 용어가 생소하다면 프롬프트 캐싱에서 설명을 확인하세요.
베타 헤더로 옵트인
거부될 수 있는 요청을 anthropic-beta: fallback-credit-2026-06-01 헤더와 함께 전송하세요. server-side-fallback-2026-06-01 헤더도 동일한 필드를 제공합니다.
거부 응답에서 두 필드 읽기
거부 시 stop_details에는 두 개의 필드가 포함됩니다.
fallback_credit_token: 크레딧을 나타내는 불투명한 문자열입니다.fallback_has_prefill_claim: 어떤 재시도 본문 형태를 사용할지 알려주는 불리언 값입니다.해당 거부에 사용할 수 있는 크레딧이 없으면 두 필드 모두 null입니다.
재시도 구성
거부된 요청 본문에서 시작하세요. model을 폴백 모델로 설정하고 토큰을 최상위 fallback_credit_token 매개변수로 추가하세요. 아래 표에서 본문 형태를 선택하세요.
동일한 헤더로 재시도 전송
동일한 fallback-credit-2026-06-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, body):
return client.beta.messages.create(
model=model, betas=["fallback-credit-2026-06-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}
# 클레임이 False가 아닌 한 연속 형태를 선호합니다
if details.fallback_has_prefill_claim is not False:
# 거부 응답의 내용을 그대로 반영하되, 마지막 텍스트 블록의 후행 공백은
# 제거합니다(프리필 검증기가 이를 거부하며, 서버 측 매칭은 이 수정을
# 허용함). 도구 사용 요청은 짝이 없는 tool_use 블록도 생략한 뒤,
# 생략 후 공백을 다시 제거합니다.
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 str(error):
raise # Transient: retry with the token within its five-minute window
try:
# 토큰을 유지한 채 변경되지 않은 본문으로 폴백합니다
response = send("claude-opus-4-8", exact_body)
except BadRequestError as error:
if "redemption temporarily unavailable" in str(error):
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, Claude Platform on AWS, Amazon Bedrock, Google Cloud, Microsoft Foundry에서 베타로 제공됩니다. Message Batches 결과에서 반환된 크레딧 토큰은 사용할 수 없습니다. 토큰 사용은 직접적인 Messages API 요청에만 적용됩니다.
재시도 모델은 거부된 모델의 허용된 폴백 대상 중 하나여야 합니다. 출시 시점에 Claude Fable 5의 허용된 대상은 Claude Opus 4.8(claude-opus-4-8)입니다.
환급은 재시도의 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?