• Messages
  • Managed Agents
  • 관리자
Search...
⌘K
첫 단계
Claude 소개빠른 시작
Claude로 빌드하기
기능 개요Messages API 사용하기중지 사유 및 폴백거부 및 폴백폴백 크레딧
모델 기능
확장 사고적응형 사고Effort작업 예산 (베타)빠른 모드 (리서치 프리뷰)구조화된 출력인용스트리밍 Messages배치 처리검색 결과스트리밍 거부다국어 지원임베딩
도구
개요도구 사용 작동 방식튜토리얼: 도구 사용 에이전트 빌드하기도구 정의도구 호출 처리병렬 도구 사용Tool Runner (SDK)엄격한 도구 사용프롬프트 캐싱과 함께 도구 사용서버 도구문제 해결웹 검색 도구웹 가져오기 도구코드 실행 도구Advisor 도구메모리 도구Bash 도구컴퓨터 사용 도구텍스트 편집기 도구
도구 인프라
도구 레퍼런스도구 컨텍스트 관리도구 조합도구 검색프로그래밍 방식 도구 호출세분화된 도구 스트리밍
컨텍스트 관리
컨텍스트 윈도우압축컨텍스트 편집프롬프트 캐싱대화 중 시스템 메시지오케스트레이션 모드 빌드하기캐시 진단 (베타)토큰 계산
파일 작업
Files APIPDF 지원이미지 및 비전
스킬
개요빠른 시작모범 사례엔터프라이즈용 스킬API에서의 스킬
MCP
원격 MCP 서버MCP 커넥터
클라우드 플랫폼의 Claude
Amazon BedrockAmazon Bedrock (레거시)AWS의 Claude PlatformMicrosoft FoundryVertex AI
Log in
폴백 크레딧
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...

Solutions

  • AI agents
  • Code modernization
  • Coding
  • Customer support
  • Education
  • Financial services
  • Government
  • Life sciences

Partners

  • Amazon Bedrock
  • Google Cloud's Vertex AI

Learn

  • Blog
  • Courses
  • Use cases
  • Connectors
  • Customer stories
  • Engineering at Anthropic
  • Events
  • Powered by Claude
  • Service partners
  • Startups program

Company

  • Anthropic
  • Careers
  • Economic Futures
  • Research
  • News
  • Responsible Scaling Policy
  • Security and compliance
  • Transparency

Learn

  • Blog
  • Courses
  • Use cases
  • Connectors
  • Customer stories
  • Engineering at Anthropic
  • Events
  • Powered by Claude
  • Service partners
  • Startups program

Help and security

  • Availability
  • Status
  • Support
  • Discord

Terms and policies

  • Privacy policy
  • Responsible disclosure policy
  • Terms of service: Commercial
  • Terms of service: Consumer
  • Usage policy
Messages/Claude로 빌드하기

폴백 크레딧

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

Was this page helpful?

  • 기본 흐름
  • 예제
  • 지원 환경
  • 크레딧 적용 여부 확인
  • 재시도가 거부될 때
  • 참조
  • 다음 단계

프롬프트 캐시는 모델별로 관리됩니다. Claude Fable 5가 요청을 거부하고 다른 모델에서 재시도할 경우, Claude Fable 5에 이미 캐시된 대화 접두사를 새 모델의 캐시에 처음부터 다시 써야 하며, 캐시 쓰기는 캐시 읽기보다 비용이 더 많이 듭니다. "Fallback credit"(폴백 크레딧)은 이러한 추가 비용을 제거합니다. 거부 응답에 크레딧 토큰이 포함되고, 재시도 시 해당 토큰을 그대로 전달하면, 재시도는 대화가 처음부터 새 모델에서 진행된 것처럼 과금됩니다.

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

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

기본 흐름

  1. 1

    베타 헤더로 옵트인

    거부될 수 있는 요청을 anthropic-beta: fallback-credit-2026-06-01 헤더와 함께 전송하세요. server-side-fallback-2026-06-01 헤더도 동일한 필드를 제공합니다.

  2. 2

    거부 응답에서 두 필드 읽기

    거부 시 stop_details에는 크레딧을 나타내는 불투명 문자열인 fallback_credit_token과, 어떤 재시도 본문 형태를 사용할지 알려주는 불리언 값인 fallback_has_prefill_claim이 포함됩니다. 해당 거부에 사용할 수 있는 크레딧이 없으면 둘 다 null입니다.

  3. 3

    재시도 구성

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

  4. 4

    동일한 헤더로 재시도 전송

    동일한 fallback-credit-2026-06-01 베타 헤더와 함께 재시도를 전송하세요. 재시도가 토큰을 사용하려면 이 헤더가 필요합니다.

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

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

예제

아래 예제는 거부될 수 있는 요청을 보내고, Claude Opus 4.8에 대한 재시도에서 크레딧 토큰을 사용하며, 재시도가 거부될 때에서 다루는 거부 단계를 따라 점진적으로 처리합니다.

지원 환경

폴백 크레딧은 Claude API, Claude Platform on AWS, Amazon Bedrock, Vertex AI, 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 오류를 반환합니다.

  1. 1

    이어쓰기 거부: 변경되지 않은 본문 재전송

    assistant 메시지를 추가한 재시도가 400 오류로 거부되면, 거부된 요청 본문을 변경하지 않고 토큰과 함께 다시 전송하세요.

  2. 2

    토큰 거부: 토큰 제거

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

거부된 요청이 서버 도구를 실행했다면, 토큰 없는 재시도는 해당 도구를 다시 실행하고 다시 과금합니다. 이 경우 토큰 없는 재시도로 넘어가지 말고 400 오류를 호출자에게 전달하세요.

참조

아래 섹션에서는 엣지 케이스와 전체 토큰 사용 규칙을 다룹니다. 대부분의 통합에서는 필요하지 않습니다.

다음 단계

거부 및 폴백

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

프롬프트 캐싱

캐시 읽기와 캐시 쓰기가 어떻게 과금되는지 알아보세요.

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가 아닌 한 continuation 형태를 선호합니다
    if details.fallback_has_prefill_claim is not False:
        # 거부 응답의 내용을 그대로 반영하되, 마지막 텍스트 블록의 후행 공백은 제거합니다
        # (prefill 검증기가 이를 거부하며, 서버 측 매칭은 이 수정을 허용합니다).
        # 도구 사용 요청의 경우 짝이 없는 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}))
중지 사유 및 폴백

모든 stop_reason 값과 처리 방법을 알아보세요.

SDK 미들웨어

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