Anthropic::BetaRefusalFallbackMiddleware

Client-side refusal fallbacks middleware.

Retries refused POST /v1/messages requests down a client-side fallback chain. Use this when the API provider does not support server-side fallbacks (the server-side-fallback-2026-07-01 beta). It is mutually exclusive with the request-body fallbacks: param.

On a stop_reason: "refusal" response, the middleware walks each fallback entry (merging model, max_tokens, thinking, output_config, and speed over the original body) and retries, carrying the refusal's fallback_credit_token in object form with mode: "best_effort" when present. The accepting hop's response is returned verbatim; a chain-exhausted refusal is also returned verbatim. Unlike server-side fallbacks, no synthetic fallback content block is inserted — inspect message.model to detect which model served.

This implementation handles the non-streaming path. For streaming fallbacks, prefer server-side fallbacks (betas: [SERVER_SIDE_FALLBACK_BETA]

• fallbacks: param) which the API handles in one round-trip.

client = Anthropic::Client.new(
  middleware: [Anthropic::BetaRefusalFallbackMiddleware.new(
    [Anthropic::FallbackParam.new(model: Anthropic::Model::CLAUDE_OPUS_4_8)],
  )],
)

message = client.beta.messages.create(
  model: Anthropic::Model::CLAUDE_FABLE_5,
  max_tokens: 1024,
  messages: [{role: "user", content: "..."}],
)