約 4 分で読めます

Claudeのrefusal再試行設計と課金・キャッシュ

エージェントが夜間バッチで走っている最中に、Claudeが stop_reason: "refusal" を返して処理が止まる。HTTPは200なので、エラー率の監視には何も映りません。しかも拒否されたリクエストの一部は課金対象で、別モデルで再試行すればプロンプトキャッシュを書き直す費用まで上乗せされます。refusal は例外処理ではなく、課金とキャッシュを含めて設計すべき通常経路です。

refusalはエラーではなく何が返るのか

refusalはHTTP 200の正常応答で返り、stop_details.category に cyber・bio・frontier_llm・reasoning_extraction・general_harms のいずれかが入ります。

安全分類器が拒否すると、応答は stop_reason: "refusal" と stop_details を持ちます。explanation の文言は安定しないため、表示用に使い、パースしてはいけません。category と explanation は、名前付きカテゴリに該当しない拒否では null になります。これは恒久的な正常値です。

  • 分岐は stop_reason か stop_details.type で行い、category の存在を前提にしない
  • 出力前の拒否でも途中の拒否でも、部分出力は不完全として破棄する
  • Message Batches の拒否は、errored ではなく succeeded の結果として返る

stop_reason の扱い方と同様に、refusal を独立した指標として集計する必要があります。可観測性基盤への組み込みはエージェントの可観測性設計も参照してください。

refusalはいつ課金されるのか

出力前の拒否はbio・frontier_llm・reasoning_extractionのみ課金され、出力途中の拒否は入力と出力済みトークンが通常料金で課金されます。

公式ドキュメントの課金ルールは次のとおりです。

拒否のタイミング課金
出力前(bio / frontier_llm / reasoning_extraction)課金される
出力前(cyber / general_harms / category が null)課金されない
出力途中入力と出力済みトークンを通常料金で課金

課金されない拒否でも usage にはトークン数が載り、レート制限には算入されます。対象カテゴリは、誤検知率の測定に応じて変わる可能性があると明記されています。固定値としてコードに埋め込まず、ドキュメントを確認する運用にしてください。

reasoning_extraction は、プロンプトに「推論過程をそのまま出力せよ」と書いたときに起きます。システムプロンプト、スキル、ツール説明のどこにあっても対象です。再試行ではなくプロンプトの修正で解消し、推論を見たい場合は display: "summarized" の thinking ブロックを使います。

再試行はどの方式を選ぶべきか

Claude APIの標準構成ならfallbacks: "default"とベータヘッダーで1回の呼び出しに閉じ、SDKミドルウェアと手動再試行は環境別に選びます。

選択基準は3つです。

  1. サーバー側fallback: fallbacks に "default" を指定し、server-side-fallback-2026-07-01 ヘッダーを付けます。API が拒否カテゴリに応じて推奨モデルへ再試行し、fallback credit も自動適用されます。自前で最大3モデルまで指定することもできます
  2. SDKミドルウェア: プラットフォームを問わず使え、クライアントに一度設定すれば自動で再試行します
  3. 手動再試行: 生のHTTPや独自ロジックの場合です。fallback credit を自分で扱います

Claude Haiku 5.5 にはサーバー側fallback も fallback credit もありません。Haiku 5.5への移行では、再試行をクライアント側で用意してください。

サーバー側fallbackの応答には fallback コンテンツブロックが入り、usage.iterations に試行ごとのトークンが記録されます。請求の根拠はこの配列で、モデルをまたいだ合算値は存在しません。次ターンでは fallback ブロックを位置を変えずに返します。スティッキールーティング(約1時間保持)で以降のターンが直接フォールバック先へ送られる場合があるため、要求モデルが再び試されることも前提に実装します。

fallback creditでキャッシュの二重課金をどう避けるか

プロンプトキャッシュはモデルごとに独立するため、別モデルへの再試行は書き込みが必要です。fallback creditがこの追加費用を打ち消します。

手動再試行では、拒否された応答の stop_details.fallback_credit_token を再試行に載せます。手順は次のとおりです。

  1. 最初のリクエストに anthropic-beta: fallback-credit-2026-07-01 を付ける
  2. 拒否応答から fallback_credit_token と fallback_has_prefill_claim を読む
  3. model をフォールバック先に変え、トップレベルに fallback_credit_token を足す。fallback_has_prefill_claim が true なら、拒否された content を末尾の assistant メッセージとして足し、続きから生成させる
  4. 同じベータヘッダーで送る

守るべき制約があります。system・messages・tools・thinking・cache_control などプロンプトを形作るフィールドは、拒否時と完全に一致させます。トークンの有効期限は5分で、発行元の組織とワークスペースにだけ有効です。Message Batches の拒否にはトークンが付きません。

再試行が400で弾かれた場合は、継続形式、元の本文のままトークン付き、トークンなしの順に段階を落とします。ただし「redemption temporarily unavailable」は一時的な拒否なので、同じ形のまま5分以内に再送します。サーバーツールが実行済みなら、トークンなしの再試行はツールを再実行して再課金するため、黙って落とさず呼び出し元にエラーを返してください。

効果は usage で確認できます。クレジットが効けば cache_creation_input_tokens が減り、cache_read_input_tokens が同量だけ増えます。per-message effortによるキャッシュ維持と同じく、キャッシュを前提にコストを見積もる設計です。

規模別の留意点(SMB / エンタープライズ)

SMBでは、まず fallbacks: "default" を有効にし、拒否率と usage.iterations を週次で確認するだけで十分です。エンタープライズでは、LLMゲートウェイに拒否の集計・カテゴリ別アラート・fallback先の許可リスト管理を集約し、Bedrock や Google Cloud 上ではサーバー側fallbackが使えない点(トークンが呼び出し元ID単位になる点も含む)をプラットフォーム別に整理します。大規模な統制設計は RDE でも扱っています。

参考

まとめ

refusalは200応答で届く課金対象の通常経路です。カテゴリ別の課金、再試行方式、fallback creditの3点を押さえれば、停止とコスト増を同時に防げます。

要点は次の3つです。拒否は専用の指標で監視すること。再試行はサーバー側fallbackかSDKミドルウェアを基本にし、手動なら fallback credit を使うこと。請求は usage.iterations で試行ごとに確認すること。

Claude APIの運用設計は、導入から定着まで伴走する AIオペレーション支援でご相談いただけます。

関連記事

プロンプトキャッシュミスの原因をAPIで特定するモデル切替でthinkingを失わない履歴設計と読み取り互換表Fast mode廃止期限と429フォールバックの設計per-message effortでキャッシュを保つ切替設計