거부 및 폴백

Claude Fable 5와 Claude Opus 5에는 요청을 거절할 수 있는 안전 분류기가 포함되어 있습니다. 이런 일이 발생하면 오류가 아니라 stop_reason: "refusal"이 포함된 정상 응답을 받게 됩니다. 일반적으로 동일한 요청을 다른 Claude 모델로 보내면 여전히 답변을 받을 수 있습니다. 이 페이지에서는 거부를 인식하는 방법과 해당 재시도를 설정하는 방법을 보여줍니다.

Claude Fable 5 또는 Claude Opus 5를 기반으로 구축하면서 거절된 요청이 자동으로 다른 모델로 넘어가기를 원할 때 이 페이지를 읽어보세요. 응답에서 방금 "refusal"을 확인했고 다음에 무엇을 해야 할지 알고 싶을 때도 해당됩니다.

관련 페이지:

• 중지 이유 및 폴백: stop_reason 값의 전체 목록.
• 폴백 크레딧: 거부된 요청의 과금 방식과 재시도 시 프롬프트 캐싱 비용을 이중으로 지불하지 않는 방법.
• SDK 미들웨어: 이 모든 것을 감싸는 SDK 헬퍼.
• 폴백 및 과금 쿡북: 처음부터 끝까지 다루는 실습 예제.

가장 간단한 설정은 Claude API에서 베타로 제공됩니다. fallbacks를 "default"로 설정하면 API가 거절된 요청을 해당 거부 카테고리에 대해 Anthropic이 권장하는 폴백 모델에서 재시도합니다. 권장 폴백이 없는 카테고리의 경우 거부가 그대로 유지됩니다.

client = Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    fallbacks="default",
    betas=["server-side-fallback-2026-07-01"],
)
print(response.model)

다음 섹션에서는 거부 응답에 포함된 내용, 서버 측 또는 클라이언트 측 폴백을 사용해야 하는 시점, 각각의 과금 방식을 다룹니다.



거부의 형태

거부는 stop_reason: "refusal"이 포함된 성공적인 HTTP 200 응답입니다:

{
  "id": "msg_01XFUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-fable-5",
  "content": [],
  "stop_reason": "refusal",
  "stop_details": {
    "type": "refusal",
    "category": "cyber",
    "explanation": "This request was declined because it could enable cyber harm."
  },
  "usage": {
    "input_tokens": 412,
    "output_tokens": 0
  }
}

stop_details 객체는 거절 사유를 설명합니다:

• category: 분류기를 트리거한 정책 영역의 이름입니다.
• explanation: 사람이 읽을 수 있는 설명입니다. 텍스트는 안정적이지 않으므로 파싱하지 말고 표시만 하세요.
• 거부가 명명된 카테고리에 매핑되지 않는 경우 두 필드 모두 null입니다. 이 null은 자리 표시자가 아니라 정상적이고 영구적인 값입니다.
• refusal 이외의 모든 중지 이유에 대해 stop_details 자체가 null입니다.

거부는 출력이 시작되기 전에 도착할 수도 있고, 부분 출력 후 스트림 중간에 도착할 수도 있습니다. 어느 경우든 부분 출력은 불완전한 것으로 간주하고 폐기하세요.



폴백 접근 방식 선택

거부된 요청을 다른 모델에서 재시도하는 방법은 세 가지입니다. 적합한 방법은 실행 환경과 필요한 제어 수준에 따라 다릅니다.

서버 측 폴백과 SDK 미들웨어는 폴백 크레딧을 자동으로 적용합니다. 재시도를 직접 구축하는 경우에만 폴백 크레딧 페이지가 필요합니다.



서버 측 폴백

서버 측 폴백은 단일 API 호출 내에서 거부된 요청을 재시도합니다. 기본 모드에서는 기본 모델이 거절하고 거부 카테고리에 권장 폴백이 있는 경우, API가 해당 카테고리에 대해 Anthropic이 권장하는 모델에서 동일한 요청을 실행합니다. 대신 최대 세 개의 자체 폴백 모델을 지정할 수도 있습니다(아래 참조). 어느 쪽이든 응답한 모델의 이름이 포함된 하나의 응답을 받게 되므로, 사용자는 한 번의 왕복으로 답변을 받습니다.



요청 보내기

fallbacks 매개변수를 문자열 "default"로 설정하고 server-side-fallback-2026-07-01 베타 헤더를 보내세요. 그러면 API가 요청된 모델의 서버 정의 기본 라우팅을 적용하며, 이는 분류기가 보고하는 거부 카테고리를 기반으로 권장 폴백 모델을 선택하므로, 권장 사항이 변경되더라도 모델 목록을 유지 관리하지 않고도 거부된 요청이 처리됩니다.

client = Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    fallbacks="default",
    betas=["server-side-fallback-2026-07-01"],
)

# usage.iterations에 fallback_message 항목이 있으면 폴백 모델이 실행되었다는 의미입니다.
# stop_reason과 함께 확인하여 폴백이 응답을 제공했는지 검증하세요.
fallback_ran = any(
    iteration.type == "fallback_message"
    for iteration in response.usage.iterations or []
)
served_by_fallback = fallback_ran and response.stop_reason != "refusal"

print(
    json.dumps(
        {
            "stop_reason": response.stop_reason,
            "model": response.model,
            "served_by_fallback": served_by_fallback,
        }
    )
)

Anthropic은 모델의 역량에 맞춰 각 모델별, 각 정책 카테고리별로 안전장치를 개별적으로 설정합니다. 카테고리에 따라 플래그가 지정된 요청은 역량이 낮은 모델로 폴백되거나 거절될 수 있습니다. "default" 모드는 이러한 모델별, 카테고리별 권장 사항을 인코딩하므로, 거부된 요청은 해당 카테고리에 대해 Anthropic이 권장하는 모델에서 재시도됩니다. 폴백은 어느 쪽이든 확인할 수 있습니다. 응답에는 처리한 모델의 이름이 포함되고, fallback 콘텐츠 블록이 전환 지점을 표시합니다.

라우팅은 서버 측에서 적용되며 Models API에서 모델별로 게시되지 않습니다. 거부된 요청을 어떤 모델이 처리했는지 확인하려면, 이 페이지의 샘플처럼 응답의 최상위 model 필드를 확인하고 usage.iterations에서 fallback_message 항목을 찾으세요.

안전 분류기의 거절만이 폴백을 트리거합니다. 요청된 모델의 속도 제한, 과부하 또는 서버 오류는 그대로 반환됩니다.



자체 폴백 모델 지정

기본 라우팅 대신 fallbacks를 최대 세 개의 모델 목록으로 설정할 수 있습니다. 요청된 모델이 거절하면 API가 체인의 다음 모델에서 동일한 요청을 실행합니다. 애플리케이션에서 검증한 모델을 고정하는 등 거부된 요청을 처리할 모델을 정확히 제어하려는 경우 이 형식을 사용하세요.

client = Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    fallbacks=[{"model": "claude-opus-4-8"}],
    betas=["server-side-fallback-2026-07-01"],
)
print(response.model)

fallbacks 목록에는 몇 가지 규칙이 적용됩니다:

• 항목은 순서대로 시도됩니다. 각 항목은 다른 항목 및 요청된 모델과 달라야 합니다.
• 각 항목은 요청된 모델의 허용된 대상 중 하나여야 합니다. 베타 헤더가 설정되면 해당 목록은 Models API의 모델 항목에 allowed_fallback_models로 게시됩니다.
• 각 항목은 model을 지정하며 해당 시도에 한해 max_tokens, thinking, output_config, speed를 재정의할 수 있습니다.
• 요청은 지정된 모든 모델에 대한 직접 요청으로서 유효해야 합니다. 폴백 모델이 요청에서 사용하는 기능을 지원하지 않으면 API가 요청을 사전에 거부합니다.
• 기본 모드와 마찬가지로 안전 분류기의 거절만이 폴백을 트리거합니다. 요청된 모델의 속도 제한, 과부하 또는 서버 오류는 그대로 반환됩니다.

명시적 목록 형식은 server-side-fallback-2026-06-01 베타 헤더에서도 작동하지만, "default" 모드는 작동하지 않습니다.

응답은 두 모드 모두 동일한 형태를 가집니다. 해당 턴을 처리한 모델이 최상위 model 필드에 나타나고, fallback 콘텐츠 블록이 전환 지점을 표시하며, usage.iterations가 각 시도를 기록합니다.



응답에 포함된 내용

응답은 다른 메시지와 동일하게 보이지만 두 가지가 추가됩니다:

• 최상위 model 필드는 반환된 메시지를 생성한 모델을 보고합니다. 이는 요청된 모델일 수도 있고 폴백 모델일 수도 있습니다.
• fallback 콘텐츠 블록은 content에서 한 모델의 출력이 다음 모델로 넘어가는 각 지점을 표시합니다: {"type": "fallback", "from": {"model": ...}, "to": {"model": ...}}.
  • from.model은 거절한 홉이 요청된 모델인 경우 보낸 모델 문자열을 그대로 반환합니다.
  • to.model은 항상 계속 진행하는 모델의 확인된 ID입니다.

출력이 시작되기 전의 거부에서는 fallback 블록이 첫 번째 콘텐츠 블록입니다. 예를 들어 기본 라우팅이 해당 거부 카테고리에 대해 Claude Opus 4.8을 선택하는 경우:

{
  "id": "msg_01XFUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-4-8",
  "content": [
    {
      "type": "fallback",
      "from": { "model": "claude-fable-5" },
      "to": { "model": "claude-opus-4-8" }
    },
    { "type": "text", "text": "Hi! How can I help you today?" }
  ],
  "stop_reason": "end_turn",
  "stop_details": null,
  "usage": {
    "input_tokens": 412,
    "output_tokens": 264,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "iterations": [
      {
        "type": "message",
        "model": "claude-fable-5",
        "input_tokens": 535,
        "output_tokens": 0,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0
      },
      {
        "type": "fallback_message",
        "model": "claude-opus-4-8",
        "input_tokens": 412,
        "output_tokens": 264,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0
      }
    ]
  }
}

usage.iterations 배열은 모든 시도를 기록합니다. 거절한 모델은 일반 message 항목으로 나타나고, 해당 턴을 처리한 모델은 fallback_message 항목으로 나타납니다. 체인의 모든 모델이 거절하면 응답은 마지막 모델의 거부가 되며, 이전 각 홉에 대한 message 항목과 마지막 홉에 대한 fallback_message 항목이 포함됩니다.



대화 계속하기

다음 턴에서는 받은 그대로 어시스턴트 콘텐츠를 다시 보내세요. 출력 중간 폴백 이후에는 content에 거절한 모델이 전환 전에 생성한 블록 유형이 포함될 수 있습니다. 다음 표는 턴을 다시 보낼 때 유지할 것과 제거할 것을 다룹니다.



스트리밍

스트리밍 요청에서는 재시도가 동일한 스트림에서 이루어지며, 이미 받은 내용은 무효화되지 않습니다. 표시되는 내용은 거절이 발생하는 시점에 따라 다릅니다.

출력이 시작되기 전에 거절이 발생하는 경우:

• message_start가 폴백 모델의 이름을 포함하고, fallback 블록이 첫 번째 콘텐츠 블록입니다.
• message_start는 폴백 시도가 시작될 때까지 기다리므로, 첫 바이트까지의 시간에 거절된 시도가 포함됩니다.

출력 중간에 거절이 발생하는 경우:

• 열려 있는 콘텐츠 블록이 닫히고, fallback 블록(델타가 없는 일반 content_block_start와 content_block_stop 쌍)이 경계를 표시합니다.
• 폴백 모델이 부분 출력에서 이어서 진행합니다. 부분 출력의 text 블록만 컨텍스트로 폴백 모델에 전달되며, 다른 블록 유형은 content에 남아 있습니다.
• message_start는 이미 요청된 모델의 이름을 포함했으므로, 처리 모델은 fallback 블록의 to.model과 최종 message_delta의 usage.iterations에 있는 fallback_message 항목에서 읽으세요.



비스트리밍 응답

비스트리밍 요청에서는 출력 중간 거절이 다르게 동작합니다. 응답에서 거절한 모델의 부분 출력이 생략되고, 폴백 모델이 처음부터 답변합니다. 결과는 출력이 시작되기 전의 거절처럼 보이며, fallback 블록이 먼저 나옵니다. 거절된 시도와 그 출력 토큰은 여전히 usage.iterations에 나타납니다.



SDK 미들웨어를 사용한 클라이언트 측 폴백

모든 Anthropic SDK에는 거부-폴백 미들웨어가 포함되어 있습니다. 폴백 모델 목록으로 클라이언트에서 한 번만 구성하면 됩니다. 그러면 client.beta.messages를 통한 호출이 모든 플랫폼에서 거부된 요청을 자동으로 재시도합니다. 미들웨어는 처리하는 모든 요청에 fallback-credit-2026-07-01 베타 헤더도 보내므로, 요청별 설정 없이 재시도 가격이 재조정됩니다.



설정하기

미들웨어를 클라이언트 생성자에 전달하고, 대화의 요청 간에 하나의 BetaFallbackState 인스턴스를 공유하세요.

from anthropic import Anthropic, BetaFallbackState, BetaRefusalFallbackMiddleware

# 거부 시 미들웨어는 나열된 폴백 모델로 재시도하고
# 처리하는 모든 요청에 폴백 크레딧 베타 헤더를 자동으로 전송합니다.
client = Anthropic(
    middleware=[BetaRefusalFallbackMiddleware([{"model": "claude-opus-4-8"}])],
)

state = BetaFallbackState()  # pins follow-ups to the model that accepted

# 스트리밍: 거부 시 미들웨어는 폴백 모델로 재시도하고
# 해당 이벤트를 열려 있는 스트림에 이어 붙입니다.
with (
    state,
    client.beta.messages.stream(
        max_tokens=1024,
        model="claude-fable-5",
        messages=[{"role": "user", "content": "Hello, Claude"}],
    ) as stream,
):
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final_message = stream.get_final_message()
print(f"\nserved by: {final_message.model}")

# 비스트리밍: 상태를 재사용하면 대화가 고정된 상태로 유지됩니다.
with state:
    message = client.beta.messages.create(
        max_tokens=1024,
        model="claude-fable-5",
        messages=[{"role": "user", "content": "Hello, Claude"}],
    )
print(f"served by: {message.model}")



동작 방식

• 재시도는 폴백 목록을 순서대로 진행합니다. 폴백 모델 자체가 거부하면 요청이 다음 항목으로 전달됩니다.
• 목록의 모든 모델이 거절하면 미들웨어는 오류를 발생시키지 않고 최종 거부(마지막 모델의 거부 응답)를 반환합니다.
• Claude Fable 5의 thinking 블록은 변경 없이 전달됩니다. 각 재시도는 원래 요청 본문을 다시 보내며, 미들웨어가 이후 요청에서 대화 기록에서 제거하는 유일한 블록은 자체적으로 추가한 fallback 경계 블록뿐입니다.
• 미들웨어를 통해 처리된 응답에는 서버 측 폴백 응답과 동일하게 각 모델 경계에 fallback 콘텐츠 블록이 포함됩니다. 미들웨어가 이후 요청에서 해당 블록을 관리합니다.
• 수락한 모델은 BetaFallbackState에 기록되므로, 상태를 공유하는 후속 요청은 거부한 모델에 다시 요청하지 않고 해당 모델에 고정됩니다.



Message Batches에서의 거부

Message Batch에서 거부된 요청은 stop_reason: "refusal"과 함께 result.type: "succeeded"로 반환됩니다. 배치 결과는 동기 응답과 동일한 stop_details 객체를 포함하므로, stop_reason 또는 stop_details.type을 통해 거부를 감지할 수 있습니다. 한 가지 차이점은 배치 거부는 폴백 크레딧을 발행하지 않으므로, 배치 결과의 stop_details에는 fallback_credit_token이 포함되지 않는다는 것입니다.

서버 측 폴백은 배치에서 사용할 수 없습니다(fallbacks를 포함하는 배치 요청은 항목별 오류 결과를 생성합니다). 거부된 배치 항목을 재시도하려면:

1. 결과에서 거부된 항목을 수집합니다.
2. 다중 턴 기록에서 Claude Fable 5의 thinking 블록을 제거합니다.
3. 새 배치 또는 직접 요청으로 폴백 모델에 다시 제출합니다.



일반적인 함정

• 다른 모델에서 재시도하세요. 거부된 요청을 동일한 모델에 다시 보내면 보통 또 다른 거부를 받게 됩니다. 재시도를 폴백 모델로 향하게 하세요.
• 턴이나 세션 단위가 아니라 요청 단위로 재시도 예산을 책정하세요. 단일 턴에서 여러 거부가 발생할 수 있습니다. 예를 들어 에이전트와 그 하위 에이전트가 있습니다.
• 모든 요청 경로에 폴백을 구성하세요. 재시도 핸들러, 오류 복구 분기, 백그라운드 워커 모두에 필요합니다. 폴백 없이 요청을 다시 발행하는 핸들러는 폴백이 가장 필요한 요청에서 보호를 잃게 됩니다.
• 하위 에이전트 호출에 자체 폴백을 제공하세요. fallbacks 매개변수는 도구 실행 내부에서 이루어지는 모델 호출로 전파되지 않습니다.
• 폴백을 주변 상태가 아니라 요청의 속성으로 만드세요. 공유 플래그, 캐시된 구성 값 또는 전역 토글은 동기화가 어긋나 요청을 조용히 보호되지 않은 상태로 둘 수 있습니다. 폴백이 활성화되어 있는지 확인할 수 없다면, 켜져 있다고 가정하지 말고 구성하세요.
• 거부를 자체 신호로 계측하세요. 거부는 HTTP 200이므로 오류율이나 5xx 응답을 기반으로 구축된 모니터링은 이를 감지하지 못합니다. 거부당 하나의 이벤트와 폴백으로 처리된 응답당 하나의 이벤트(usage.iterations의 fallback_message 항목이 후자를 표시)를 발행한 다음, 두 수치 간의 차이에 대해 알림을 설정하세요.
• content나 내부 stop_details 필드가 아니라 stop_reason 또는 stop_details.type으로 분기하세요. stop_details 객체는 거부 시 항상 존재하지만, category와 explanation 필드는 null일 수 있습니다. stop_reason이 "refusal"과 같은지 직접 확인하세요.



다음 단계