Claude Platform Docs
Messages使用 Claude 進行開發

拒絕與備援

Claude Fable 模型、Claude Opus 模型、Claude Sonnet 5.5 和 Claude Haiku 5.5 如何回傳分類器拒絕,以及如何在備援模型上重試被拒絕的請求。

Claude Fable 5.1、Claude Fable 5、Claude Opus 5.5、Claude Opus 5、Claude Sonnet 5.5 和 Claude Haiku 5.5 包含可能拒絕請求的「safety classifier」(安全分類器)。發生這種情況時,您會收到一個正常的回應,而不是錯誤,其中帶有 stop_reason: "refusal"。其 stop_details.category 會指出政策領域(請參閱拒絕的樣貌)。您通常仍可透過將相同請求傳送至另一個 Claude 模型來取得答案。本頁說明如何辨識拒絕,以及如何設定該重試。

當您以上述任一模型進行開發,並希望被拒絕的請求能自動轉交給另一個模型時,請閱讀本頁。若您已在回應中看到 "refusal" 並想知道下一步該怎麼做,本頁同樣適用。

相關頁面:

最簡單的設定(在 Claude API 上為 beta 版):將 fallbacks 設為 "default",API 便會在 Anthropic 針對該拒絕類別所建議的備援模型上重試被拒絕的請求。對於沒有建議備援模型的類別,拒絕將維持不變。Claude Haiku 5.5 沒有伺服器端備援,因此請改用搭配 SDK 中介軟體的用戶端備援或自行撰寫重試。

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: 人類可讀的描述。此文字並不穩定,因此請直接顯示而非解析它。
  • recommended_model: 僅出現在設定了 fallbacks 的請求上(伺服器端備援,beta)。當 API 略過備援嘗試時(例如備援模型受到速率限制),它會指出可直接重試的模型,否則為 null。這是一個提示,而非保證。
  • 當拒絕無法對應到具名類別時,category 與 explanation 皆為 null。該 null 是正常且永久的值,而非佔位符。
  • 對於 refusal 以外的所有停止原因,stop_details 本身為 null。
category含義在產生任何輸出前即計費
"cyber"該請求可能促成網路危害,例如惡意軟體或漏洞利用程式開發。良性的網路安全工作也可能觸發此類別。否
"bio"該請求可能促成生物危害,例如危險的實驗室方法。有益的生命科學工作也可能觸發此類別。是
"frontier_llm"該請求可能協助開發競爭性 AI 模型,這在 Anthropic 的商業條款下受到限制。良性的機器學習工作也可能觸發此類別。是
"reasoning_extraction"該請求要求模型在回應文字中重現其內部推理。若要改以結構化形式取得推理,請使用自適應思考。請參閱將推理保留在思考區塊中。是
"general_harms"該請求屬於上述四個具名類別以外的使用政策領域。良性工作也可能觸發此類別。否

拒絕可能在任何輸出之前到達,也可能在部分輸出後於串流中途到達。無論哪種情況,請將任何部分輸出視為不完整並捨棄。

將推理保留在思考區塊中

reasoning_extraction 拒絕通常來自要求模型將其思考或推理放入輸出中的提示,無論是逐字或以固定格式。常見範例:

  • 模型在回答前填寫的 <thinking>、<reasoning> 或草稿區段
  • JSON 輸出或工具輸入中的 reasoning、thinking 或 trace 欄位
  • 模型的私人筆記,或其推理的持續記錄
  • 要求逐字或完整呈現的推理

這類措辭可能出現在系統提示、技能或工具描述中,因此也請檢查這些地方。

您仍然可以要求 Claude 解釋其答案。請要求簡短的解釋、結果背後的證據,或其所採取行動的摘要。若要查看模型如何推理,請設定 display: "summarized" 並閱讀 thinking 區塊。此類別沒有建議的備援模型,因此請修改提示,而不是重試請求。如果改寫後的請求仍被拒絕,請聯絡支援團隊並附上請求 ID。

拒絕的計費方式

這些計費規則適用於所有平台:Claude API、Amazon Bedrock、Claude Platform on AWS、Google Cloud 和 Microsoft Foundry。

產生任何輸出前的拒絕: 為了阻止大規模規避 Anthropic 防護措施的企圖,在任何輸出之前到達的拒絕,若其 stop_details.category 為 "bio"、"frontier_llm" 或 "reasoning_extraction",就會計費。截至 2026 年 9 月,這些是 Anthropic 測得「false positive」(誤判)數量較低的類別。這些拒絕的計費方式與其他請求相同,依執行該請求之模型的費率計算。在任何輸出之前到達、但屬於其他類別或類別為 null 的拒絕則不計費。無論哪種情況,content 皆為空,token 計數會出現在 usage 中。該請求仍會計入您的速率限制。

串流中途的拒絕: 串流中途的拒絕會以正常費率計收輸入 token 以及已串流的輸出。

備援: 當您使用備援時,若觸發備援的拒絕是在串流中途出現,或屬於計費類別之一,則除了備援請求之外,該拒絕也會計費。備援抵免會補償備援請求的提示快取未命中,因此您無需為快取對話支付兩次費用。Claude Haiku 5.5 的拒絕不附帶備援抵免,因此在其之後的備援需支付寫入備援模型提示快取的全額成本。關於伺服器端備援如何回報每次嘗試,請參閱計費與速率限制。

隨著 Anthropic 持續測量並改善其防護措施的誤判率,計費類別可能會有所變動。拒絕類別表中的在產生任何輸出前即計費欄位列出了計費類別。

選擇備援方式

有三種方式可在另一個模型上重試被拒絕的請求。合適的方式取決於您的執行環境以及您需要多少控制權。

您的情況使用原因
Claude API,最簡單的設定伺服器端備援一個請求,一個回應。API 處理重試。
任何平台,使用 Anthropic SDKSDK 中介軟體在用戶端設定一次。重試自動進行。
原始 HTTP 或自訂重試邏輯手動重試搭配備援抵免完全控制。備援抵免可降低成本。

伺服器端備援和 SDK 中介軟體會為您套用備援抵免。只有在您自行建構重試時,才需要參閱備援抵免頁面。Claude Haiku 5.5 既沒有伺服器端備援也沒有備援抵免,因此請使用 SDK 中介軟體或手動重試。

伺服器端備援

伺服器端備援(server-side fallback)在單一 API 呼叫內重試被拒絕的請求。在預設模式下,當主要模型拒絕且該拒絕類別有建議的備援時,API 會在 Anthropic 針對該類別建議的模型上執行相同請求。您也可以改為自行指定最多三個備援模型。無論哪種方式,您都會收到一個指出回答模型的回應,因此您的使用者在一次往返中即可獲得答案。

發出請求

將 fallbacks 參數設為字串 "default",並傳送 server-side-fallback-2026-07-01 beta 標頭。API 隨後會套用所請求模型的伺服器定義預設路由,該路由會根據分類器回報的拒絕類別選擇建議的備援模型,因此被拒絕的請求可獲得服務,而您無需在建議變更時維護模型清單。

預設路由絕不會因您未選擇的模型而引發預先的過大圖片拒絕:若某個路由模型會縮放標記為 "oversized_image": "error" 的圖片,該模型會從路由中移除,因此已標記的圖片絕不會以縮放後的形式提供。

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 會在相同請求上執行鏈中的下一個模型。當您想精確控制由哪些模型服務被拒絕的請求時(例如固定使用您的應用程式已驗證合格的模型),請使用此形式。

具名的備援模型會計入過大圖片檢查:若請求的圖片區塊設定了 "oversized_image": "error",則會預先針對所請求的模型及每個具名備援進行檢查,只要其中任一模型會縮放該圖片,請求即被拒絕,且拒絕所回報的縮放目標適用於所有這些模型。

醒目標示的行是與預設路由請求唯一的差異。

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 會預先拒絕該請求。在 2026-07-01 標頭下,thinking: {"type": "between_tools"} 是例外:當 Claude Sonnet 5.5 請求備援至 Claude Sonnet 5 時,備援嘗試會以 thinking: {"type": "disabled"} 和 display: "omitted" 執行。在 2026-06-01 下,請在 Claude Sonnet 5 項目上設定 thinking,否則請求會被預先拒絕。
  • 與預設模式相同,只有安全分類器的拒絕才會觸發備援。所請求模型上的速率限制、過載或伺服器錯誤會原樣傳回給您。
  • 如果備援模型受到速率限制或過載,則不會進行備援嘗試,而是改為傳回前一個拒絕。此時該拒絕的 stop_details.recommended_model 會指出一個可直接重試的模型。請依據您預期的拒絕量來規劃備援模型的速率限制,否則在高負載下備援會退化為拒絕。

兩種模式下的回應結構相同:服務該輪次的模型出現在頂層 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 項目。

黏性路由可將後續輪次直接傳送至備援模型。這樣的輪次不帶 fallback 內容區塊,因為該輪次沒有模型拒絕。請透過 usage.iterations 中的 fallback_message 項目、所請求模型沒有 message 項目,以及回應的 model 欄位來辨識它。

延續對話

在下一輪次,請將助理內容依您收到的原樣傳回。在輸出中途備援之後,content 可能包含拒絕模型在交接前產生的區塊類型。下表說明當您回顯該輪次時,哪些應保留、哪些應捨棄。

區塊類型在下一輪次
fallback精確保留在其出現的位置。API 使用其位置來驗證其周圍的思考區塊,因此若該區塊被省略或移動,回顯邊界兩側思考區塊的請求會被拒絕。
text保留。
最後一個 fallback 區塊之後的任何區塊保留。
最後一個 fallback 區塊之前的 thinking、redacted_thinking 或 connector_text捨棄。
最後一個 fallback 區塊之前的用戶端 tool_use捨棄。
最後一個 fallback 區塊之前的 server_tool_use與其結果配對時保留。沒有對應結果時捨棄。

串流

在串流(streaming)請求上,重試在同一個串流上進行,且您已收到的任何內容都不會失效。您看到的內容取決於拒絕發生的時間點。

當拒絕發生在任何輸出之前:

  • message_start 指出備援模型,且 fallback 區塊是第一個內容區塊。
  • 由於 message_start 會等待備援嘗試開始,首位元組時間包含被拒絕的嘗試。

當拒絕發生在輸出中途:

  • 開啟中的內容區塊會關閉,而 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 中。

計費與速率限制

每次嘗試都遵循拒絕的計費方式中的規則,並依執行該嘗試之模型的費率計算。在產生任何輸出之前即拒絕的嘗試,只有在其拒絕類別屬於計費類別時才會計費,且無論如何,其 token 都會回報於其 usage.iterations 項目上。每個產生了輸出的嘗試(包括在回應中途拒絕的嘗試)都會分別計費。usage.iterations 陣列是您被計費內容的逐次嘗試記錄。頂層 usage 計數僅描述產生所回傳訊息的那次嘗試。來自不同模型的 token 絕不會加總到同一個欄位中。

每次執行的嘗試(包括拒絕的嘗試)都會計入其自身模型的速率限制。

黏性路由

對話備援之後,API 會記錄由哪個模型服務。該對話後續包含 fallbacks 的請求會直接送往該備援模型,而不執行所請求的模型。這可避免在每一輪次為可預期會再次被拒絕的嘗試付費。

路由決策的幾項特性:

  • 保留約 1 小時,且範圍限於您的組織。
  • 以對話前綴的內容雜湊加上服務它的模型來儲存。訊息內容本身不會被儲存。
  • 屬於盡力而為,因此您的程式碼必須能處理所請求的模型在任何時候被再次嘗試的情況。

黏性路由(sticky routing)同時適用於串流與非串流請求。在串流請求上,路由決策在串流開啟前做出,因此 message_start 事件的 model 欄位已帶有備援模型的 ID。

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

SDK 包含一個拒絕備援中介軟體。您只需在用戶端上以您的備援模型清單設定一次。之後透過 client.beta.messages 的呼叫便會在任何平台上自動重試被拒絕的請求。中介軟體也會在其處理的每個請求上傳送 fallback-credit-2026-07-01 beta 標頭,因此重試會重新計價,無需逐一設定請求。Claude Haiku 5.5 的拒絕不附帶備援抵免,因此在其之後的重試需支付寫入備援模型提示快取的全額成本。

設定方式

將 BetaRefusalFallbackMiddleware 傳遞給用戶端建構函式,並在一個對話的各請求之間共用一個 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.1、Claude Opus 5.5、Claude Sonnet 5.5、Claude Haiku 5.5 或 Claude Fable 5 的思考區塊會原封不動地傳遞。每次重試都會重新傳送您原始的請求主體,而中介軟體在後續請求中從對話歷史移除的唯一區塊,是它自己新增的 fallback 邊界區塊。備援模型無法讀取 Claude Fable 5.1 區塊,因為只有 Claude Fable 5.1 和 Claude Mythos 5.1 能讀取,因此 API 會捨棄它們。對於 Claude Fable 5.1 和 Claude Mythos 5.1 以外的所有備援模型,API 也會捨棄 Claude Opus 5.5 區塊(請參閱在對話中途切換模型)。對於 Claude API 和 Google Cloud 上的 Claude Opus 5.5 以外的所有備援模型,它也會捨棄 Claude Sonnet 5.5 區塊。Claude Opus 5.5 和 Claude Sonnet 5.5 在 Claude API 和 Google Cloud 上能讀取 Claude Haiku 5.5 區塊,而對於無法讀取它們的備援模型,API 會將其捨棄。
  • 透過中介軟體處理的回應會在每個模型邊界包含一個 fallback 內容區塊,與伺服器端備援回應相同。中介軟體會在後續請求中為您管理這些區塊。
  • 接受請求的模型會記錄在 BetaFallbackState 中,因此共用該狀態的後續請求會固定使用該模型,而不會再次詢問曾拒絕的模型。

自行撰寫重試

透過原始 HTTP 或自訂重試邏輯,實作中介軟體所封裝的模式:

  1. 偵測拒絕

    檢查回應中是否有 stop_reason: "refusal"。

  2. 在備援模型上重新傳送

    傳送相同的請求,並將 model 設為備援模型,例如 Claude Opus 4.8。如果被拒絕的請求傳送了 thinking: {"type": "between_tools"},請先變更 thinking:只有 Claude Sonnet 5.5 接受該值,因此請省略 thinking 或設定備援模型接受的值。在 2026-07-01 標頭下,伺服器端備援在備援至 Claude Sonnet 5 時會為您進行此變更。另一個模型通常可以為 Claude Fable 5.1 或 Claude Fable 5 拒絕的請求提供服務。您如何處理對話歷史記錄,取決於您是否兌換備援抵免:

    • 不兌換額度: 您可以保留先前的 thinking 和 redacted_thinking 區塊,或將其移除以節省輸入 token。無論哪種方式,備援模型通常都無法使用它們:只有 Claude Fable 5.1 和 Claude Mythos 5.1 能讀取 Claude Fable 5.1 區塊,而只有這兩個模型、Claude Fable 5 和 Claude Mythos 5 能讀取 Claude Fable 5 區塊,因此對於任何其他備援模型,API 會將其捨棄。對於 Claude Fable 5.1 和 Claude Mythos 5.1 以外的所有備援模型,API 也會捨棄 Claude Opus 5.5 區塊(請參閱在對話中途切換模型)。對於 Claude API 和 Google Cloud 上的 Claude Opus 5.5 以外的所有備援模型,它也會捨棄 Claude Sonnet 5.5 區塊。Claude Haiku 5.5 拒絕後的重試一律屬於此情況。Claude Opus 5.5 和 Claude Sonnet 5.5 在 Claude API 和 Google Cloud 上能讀取 Claude Haiku 5.5 區塊,因此當您在這些平台上備援至其中任一模型時,請保留這些區塊。對於無法讀取它們的備援模型,API 會將其捨棄且不計費。
    • 兌換額度: 請原封不動地傳送主體,因為兌換需要完全相符。兌換時,伺服器會處理先前模型的思考區塊,因此請勿移除它們(請參閱必須與被拒絕請求相符的欄位)。
  3. 持續使用備援模型

    對於多輪對話,請在後續輪次中持續使用備援模型,而不要切換回原模型。

手動重試會從頭寫入備援模型的提示快取,這比讀取現有快取的成本更高。備援抵免會退還該成本;請在您自行建構的每次重試中兌換它。Claude Haiku 5.5 的拒絕不附帶備援抵免,因此在其之後的重試需支付寫入備援模型提示快取的全額成本。

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. 保留多輪歷史中的思考區塊,或將其移除以節省輸入 token。對於無法讀取它們的備援模型,API 會將其捨棄且不計費,與手動重試相同。
  3. 如果被拒絕的項目傳送了 thinking: {"type": "between_tools"},請省略 thinking 或設定備援模型接受的值。只有 Claude Sonnet 5.5 接受 between_tools。
  4. 在備援模型上以新批次或直接請求的方式重新提交它們。

常見陷阱

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

後續步驟

當您自行建構重試時,避免重複支付提示快取成本。

每個 stop_reason 值及其處理方式。

SDK 中介軟體的運作方式,包括拒絕備援輔助工具。

將現有應用程式遷移至 Claude Fable 5.1。

Was this page helpful?