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

> Claudeのstop_reason refusalは200応答で返り、カテゴリにより課金されます。サーバー側fallback・SDK・手動再試行の使い分けとfallback creditでキャッシュ二重課金を避ける設計を整理します。

- Canonical: https://kuucorp.com/blog/claude-refusal-fallback-credit-retry-billing-design/
- Date: 2026-11-05
- Last modified: 2026-11-05
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
エージェントが夜間バッチで走っている最中に、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 の扱い方](/blog/claude-stop-reason-handling-agent-loop-design-smb/)と同様に、refusal を独立した指標として集計する必要があります。可観測性基盤への組み込みは[エージェントの可観測性設計](/blog/agent-observability-tracing-instrumentation/)も参照してください。

## 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への移行](/blog/claude-haiku-5-5-migration-tiered-pricing-smb/)では、再試行をクライアント側で用意してください。

サーバー側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によるキャッシュ維持](/blog/claude-per-message-effort-cache-preserving-routing-design/)と同じく、キャッシュを前提にコストを見積もる設計です。

### 規模別の留意点（SMB / エンタープライズ）

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

## 参考

- [Refusals and fallback（Claude Docs）](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback)
- [Fallback credit（Claude Docs）](https://platform.claude.com/docs/en/build-with-claude/fallback-credit)
- [Handle streaming refusals（Claude Docs）](https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)

## まとめ

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

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

Claude APIの運用設計は、導入から定着まで伴走する [AIオペレーション支援](https://kuucorp.com/services/ai-ops/)でご相談いただけます。
