거부 및 폴백

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

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

stop_reason 값의 전체 목록은 중지 이유 및 폴백에 있습니다. 거부된 요청이 어떻게 청구되는지, 그리고 재시도 시 프롬프트 캐싱 비용을 두 번 지불하지 않는 방법에 대한 자세한 내용은 폴백 크레딧에 있습니다. 이 모든 것을 래핑하는 SDK 헬퍼는 SDK 미들웨어에 있습니다. 전체 과정을 다룬 예제는 폴백 및 청구 쿡북을 참조하세요.

가장 간단한 설정: 요청에 폴백 모델을 지정하면 API가 재시도를 처리합니다.

await client.beta.messages.create({
  model: "claude-fable-5",
  max_tokens: 1024,
  messages,
  betas: ["server-side-fallback-2026-06-01"],
  fallbacks: [{ model: "claude-opus-4-8" }]
});

아래 섹션에서는 거부 응답에 포함된 내용, 서버 측 또는 클라이언트 측 폴백을 사용해야 하는 경우, 그리고 각각의 청구 방식을 다룹니다.

거부 응답의 형태

거부는 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은 플레이스홀더가 아니라 정상적이고 영구적인 값입니다. stop_details 자체는 refusal 이외의 모든 중지 이유에 대해 null입니다.

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

폴백 방식 선택하기

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

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

서버 측 폴백

서버 측 폴백은 단일 API 호출 내에서 거부된 요청을 재시도합니다. 최대 세 개의 폴백 모델을 지정하면, Claude Fable 5가 거부할 때 API가 동일한 요청에 대해 체인의 다음 모델을 실행합니다. 응답한 모델의 이름이 포함된 하나의 응답을 받게 되므로, 사용자는 한 번의 왕복으로 답변을 얻습니다.

요청 보내기

fallbacks 매개변수에 폴백 모델을 지정하고 server-side-fallback-2026-06-01 베타 헤더를 전송하세요.

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-06-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,
        }
    )
)

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

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

응답에 포함된 내용

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

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

출력이 생성되기 전의 거부에서는 fallback 블록이 첫 번째 콘텐츠 블록입니다:

{
  "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 미들웨어를 사용한 클라이언트 측 폴백

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

설정하기

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

# 거부 시 미들웨어는 나열된 폴백 모델로 재시도하고
# 처리하는 모든 요청에 폴백 크레딧 베타 헤더를 자동으로 전송합니다.
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 event in stream:
        if event.type == "text":
            print(event.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 콘텐츠 블록을 포함합니다. 미들웨어는 이후 요청에서 해당 블록을 자동으로 관리합니다.
• 수락한 모델은 BetaFallbackState에 기록되므로, 상태를 공유하는 후속 요청은 거부한 모델에 다시 요청하지 않고 해당 모델에 고정됩니다.

Message Batches의 거부

Message Batch에서 거부된 요청은 result.type: "succeeded"와 stop_reason: "refusal"로 반환됩니다. 배치 결과에서 stop_details 필드는 null일 수 있으므로, stop_reason을 직접 확인하여 거부를 감지하세요.

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

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

일반적인 실수

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

다음 단계