Handle Claude Refusals in One Line: The API's fallbacks: 'default' Server-Side Fallback

Add fallbacks: "default" and one beta header to your /v1/messages call — when Claude's safety classifier declines, the API retries on Anthropic's recommended safe alternative in the same round trip.

When a Claude model declines a request for safety reasons, your code normally receives a stop_reason: "end_turn" response with no useful content. Detecting that, deciding what to do, and retrying is extra logic in every agent that calls the API. The server-side fallback beta removes that loop for safety-classifier declines.

The change

Add two things to any /v1/messages call:

response = client.messages.create(
    model="claude-fable-5-20260201",
    max_tokens=1024,
    messages=[{"role": "user", "content": prompt}],
    fallbacks="default",                                         # <- add this
    extra_headers={
        "anthropic-beta": "server-side-fallback-2026-07-01"     # <- and this
    }
)

# Check which model actually served the response:
print(response.model)   # may differ from "claude-fable-5-20260201"

When the primary model's classifier declines, the API immediately retries on Anthropic's recommended alternative for that refusal category. You get one response — already answered — in the same round trip, with no error surfaced to your caller.

Three things to know

1. Only safety-classifier declines trigger the fallback. Overload errors (429/529), token-limit hits, and network errors are not covered — handle those with your existing retry logic or fallbackModel in Claude Code config.

2. Direct API only. The fallbacks parameter is not available on Amazon Bedrock, Google Cloud Vertex, or Microsoft Foundry — only the Anthropic API.

3. Track per-model usage. The response's model field shows which model served it. Check usage.iterations for per-model token accounting when billing back to teams or cost-tracking by model.

You can also pass an explicit list of up to three fallback models instead of "default":

fallbacks=["claude-opus-5-20260201", "claude-sonnet-5-20260130"]

The "default" mode is the easier path for most teams — Anthropic updates the recommended fallback chain as models change, so your code stays current without maintenance.

Sources: Refusals and Fallback — Claude Platform Docs · Fallback Credit — Claude Platform Docs · Classifier Fallback and Billing — Claude Cookbook