拒絕與後備

Claude Fable 5 和 Claude Opus 5 包含可以拒絕請求的安全分類器。當這種情況發生時，您會收到一個正常的回應（而非錯誤），其中帶有 stop_reason: "refusal"。您通常仍然可以透過將相同的請求傳送到另一個 Claude 模型來取得答案。本頁說明如何辨識拒絕，以及如何設定該重試。

當您在 Claude Fable 5 或 Claude Opus 5 上進行建置，並希望被拒絕的請求自動轉移到另一個模型時，請閱讀本頁。當您剛在回應中看到 "refusal" 並想知道下一步該怎麼做時，本頁也適用。

相關頁面：

• 停止原因與後備：stop_reason 值的完整清單。
• 後備額度：被拒絕的請求如何計費，以及如何避免在重試時為提示快取支付兩次費用。
• SDK 中介軟體：封裝所有這些功能的 SDK 輔助工具。
• 後備與計費 cookbook：一個完整的端到端範例。

最簡單的設定（在 Claude API 上為 beta 版）：將 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)

以下各節涵蓋拒絕回應包含的內容、何時使用伺服器端或用戶端後備，以及各自的計費方式。



拒絕的樣貌

拒絕是一個成功的 HTTP 200 回應，帶有 stop_reason: "refusal"：

{
  "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 beta 標頭。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 清單適用以下幾條規則：

• 項目會按順序嘗試。每個項目必須與其他項目以及所請求的模型不同。
• 每個項目必須是所請求模型的允許目標之一。設定 beta 標頭後，該清單會以 allowed_fallback_models 的形式發布在 Models API 中該模型的項目上。
• 每個項目指定一個 model，並且可以僅針對該次嘗試覆寫 max_tokens、thinking、output_config 和 speed。
• 該請求必須對每個指定的模型都是有效的直接請求。如果後備模型不支援請求所使用的功能，API 會預先拒絕該請求。
• 與預設模式相同，只有安全分類器的拒絕會觸發後備。所請求模型上的速率限制、過載或伺服器錯誤會原樣回傳給您。

明確清單形式在 server-side-fallback-2026-06-01 beta 標頭下也可運作；"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 會等待後備嘗試開始，首位元組時間（time to first byte）包含被拒絕的嘗試。

當拒絕在輸出中途發生時：

• 開啟的內容區塊會關閉，而 fallback 區塊（一個沒有 delta 的一般 content_block_start 和 content_block_stop 配對）標記邊界。
• 後備模型從部分輸出繼續。只有部分輸出的 text 區塊會作為上下文傳遞給後備模型；其他區塊類型保留在 content 中。
• message_start 已經指明了所請求的模型，因此請從 fallback 區塊的 to.model 以及最終 message_delta 的 usage.iterations 中的 fallback_message 項目讀取提供服務的模型。



非串流回應

在非串流請求上，輸出中途的拒絕行為有所不同：回應會省略被拒絕模型的部分輸出，而後備模型會從頭開始回答。結果看起來像是在任何輸出之前的拒絕，fallback 區塊在最前面。被拒絕的嘗試及其輸出 token 仍會出現在 usage.iterations 中。



搭配 SDK 中介軟體的用戶端後備

每個 Anthropic SDK 都包含一個拒絕後備中介軟體。您在用戶端上使用您的後備模型清單設定一次。透過 client.beta.messages 的呼叫接著會在任何平台上自動重試被拒絕的請求。該中介軟體還會在它處理的每個請求上傳送 fallback-credit-2026-07-01 beta 標頭，因此重試會重新計價，無需按請求設定。



設定方式

將中介軟體傳遞給用戶端建構函式，並在對話的各個請求之間共用一個 BetaFallbackState 實例。

from anthropic import Anthropic, BetaFallbackState, BetaRefusalFallbackMiddleware

# 發生拒絕時，中介軟體會改用所列的備援模型重試，並
# 在其處理的每個請求上自動送出 fallback-credit beta 標頭。
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 的思考區塊會原樣通過：每次重試都會重新傳送您的原始請求主體，而中介軟體在後續請求中從對話歷史中移除的唯一區塊是它自己新增的 fallback 邊界區塊。
• 透過中介軟體服務的回應在每個模型邊界都包含一個 fallback 內容區塊，與伺服器端後備回應相同。中介軟體會在後續請求中為您管理這些區塊。
• 接受的模型會記錄在 BetaFallbackState 中，因此共用該狀態的後續請求會固定使用它，而不是再次詢問已拒絕的模型。



Message Batches 中的拒絕

Message Batch 中被拒絕的請求會以 result.type: "succeeded" 和 stop_reason: "refusal" 回傳。批次結果帶有與同步回應相同的 stop_details 物件，因此您可以透過 stop_reason 或 stop_details.type 偵測拒絕。有一個差異：批次拒絕不會產生後備額度，因此批次結果上的 stop_details 永遠不會包含 fallback_credit_token。

伺服器端後備不適用於批次（包含 fallbacks 的批次請求會產生逐項錯誤結果）。若要重試被拒絕的批次項目：

1. 從結果中收集被拒絕的項目。
2. 從任何多輪歷史中移除 Claude Fable 5 的思考區塊。
3. 將它們作為新批次或直接請求在後備模型上重新提交。



常見陷阱

• 在不同的模型上重試。 將被拒絕的請求重新傳送到同一個模型通常會再次被拒絕。請將重試指向後備模型。
• 按請求而非按輪次或按工作階段來預算重試。 單一輪次可能產生多個拒絕，例如一個代理加上其子代理。
• 在每個請求路徑上設定後備。 重試處理常式、錯誤復原分支和背景工作程式都需要它。在沒有後備的情況下重新發出請求的處理常式，恰恰會在最可能需要保護的請求上失去保護。
• 為子代理呼叫提供它們自己的後備。 fallbacks 參數不會傳播到工具執行內部發出的模型呼叫。
• 讓後備成為請求的屬性，而非環境狀態的屬性。 共用旗標、快取的設定值或全域開關可能會失去同步，並在無聲中讓請求失去保護。當您無法確認後備是否啟用時，請設定它，而不要假設它已開啟。
• 將拒絕作為獨立訊號進行監測。 拒絕是 HTTP 200，因此建立在錯誤率或 5xx 回應上的監控永遠看不到它。為每個拒絕發出一個事件，為每個由後備服務的回應發出一個事件（usage.iterations 中的 fallback_message 項目標記後者），然後針對兩個計數之間的差距發出警報。
• 根據 stop_reason 或 stop_details.type 分支，而非根據 content 或內部的 stop_details 欄位。 stop_details 物件在拒絕時始終存在，但其 category 和 explanation 欄位可能為 null。請直接檢查 stop_reason 是否等於 "refusal"。



後續步驟