AI Model Refusal Design: Building Products That Handle Declines Gracefully
TL;DR
Claude Fable 5 introduced a new API behavior: when its safety classifiers decline a request, the response returns HTTP 200 with stop_reason: "refusal", not an error. Products that treat this like an error or ignore it entirely ship broken user experiences. You need three things: refusal detection logic, a fallback strategy (server-side, client-side SDK, or manual), and a UX pattern that keeps users informed. This article covers the mechanics, the classifier categories, fallback options, the billing rules, and how to decide when a safety-constrained versus unrestricted model tier is the right architectural choice.
The AI PM Minute
One tactic to make you a sharper AI PM, twice a week. 60 seconds to read. Free.
No fluff. Unsubscribe anytime.
How Fable 5 Refusals Differ from What Came Before
Before Claude Fable 5, a model refusing a request was not a formal API event. The model might produce a polite refusal as text output, but the API response looked identical to a successful completion: stop_reason: "end_turn". Your application had no way to distinguish "Claude answered the question" from "Claude declined to answer the question" without parsing the output text.
Claude Fable 5 changes this. Safety classifiers now run as a distinct layer in the inference pipeline. When a classifier declines a request, the API returns a structured refusal response: an HTTP 200 (not a 4xx or 5xx error) with stop_reason: "refusal". The response body also includes stop_details with a category field identifying which classifier triggered.
{
"id": "msg_...",
"stop_reason": "refusal",
"stop_details": {
"type": "refusal",
"category": "harmful_content"
},
"content": [],
"usage": {
"input_tokens": 124,
"output_tokens": 0
}
}Notice output_tokens: 0. When a request is refused before any output is generated, you are not billed for output tokens. Only input tokens are charged. This matters for cost modeling: your application may retry on a different model and you will not be double-billed for the refused output.
Important: this is not an error
HTTP 200 means your API call succeeded. The refusal is a structured outcome, not an exception. If your error handling only catches 4xx and 5xx responses, you will silently receive empty content and no explanation. You must explicitly check stop_reason for every response.
Refusal Categories and What Triggers Them
The stop_details.category field tells you which safety classifier declined the request. Understanding the category matters because different categories warrant different product responses.
harmful_contentWhat it means: The request asks the model to generate content that could cause real-world harm. This is the most common category. Covers violence, CSAM, weapons synthesis, and similar absolute limits.
Recommended response: Surface an error to the user explaining the request cannot be fulfilled. Do not retry on another model. This category represents content your product should not generate regardless of model.
reasoning_extractionWhat it means: The request attempts to elicit the model's internal reasoning chain as part of the response text. Anthropic treats the raw chain of thought as proprietary on Fable 5.
Recommended response: Revise the prompt. If you need reasoning visibility for debugging, use thinking.display: summarized instead of prompting the model to explain its reasoning inline.
contextualWhat it means: The classifier determined the request is not appropriate in the context of the current conversation or system prompt configuration. More nuanced than absolute limits.
Recommended response: Retry on another Claude model using the fallback mechanism. A different model may serve the same request without classifier conflict. Log the category for pattern analysis.
policyWhat it means: Platform or API policy violation. May relate to account-level restrictions, geographic restrictions from export controls, or usage policy conditions.
Recommended response: Review your API account status and usage policies. This category often requires human investigation rather than automated retry.
Three Fallback Strategies and When to Use Each
When Fable 5 refuses a request, the same request can often be served by a different Claude model without a classifier. Anthropic provides three fallback mechanisms with different tradeoffs.
Server-side fallback (beta)
Pass a fallbacks parameter in your API call listing the models to try in order. If Fable 5 refuses, the API automatically retries on the next model in your list without a round trip to your application.
Pros
No additional code in your application. Lowest latency on retry because there is no round trip. Billing is handled correctly automatically.
Cons
Beta feature. Available on Claude API and Claude Platform on AWS. Check documentation for current availability.
{
"model": "claude-fable-5",
"fallbacks": ["claude-sonnet-5", "claude-opus-4-8"],
"messages": [...]
}Client-side SDK middleware
The Anthropic SDK (TypeScript, Python, Go, Java, C#) includes middleware hooks that intercept refusal responses and retry on another model automatically. Configure once in your client initialization.
Pros
Works on any platform. More control over retry logic, logging, and alerting. Can be combined with custom metrics collection.
Cons
Extra round trip from your application to the API. Slightly higher latency on the refusal path.
const client = new Anthropic({
middleware: refusalFallbackMiddleware({
fallbacks: ["claude-sonnet-5"]
})
})Manual retry
In your application code, check stop_reason after every Fable 5 response. If refusal, make a new API call to your fallback model with the original request body.
Pros
Maximum flexibility. Works in any language. Full control over which requests retry and on what conditions.
Cons
Most code to write. Need to handle fallback credit claims manually if you want cost offsets.
if (response.stop_reason === "refusal") {
const fallback = await client.messages.create({
model: "claude-sonnet-5",
messages: originalMessages
})
}Fallback credit: avoid paying twice
If your request used prompt caching on Fable 5 and was then refused, retrying on another model would normally re-pay the cache write cost. Fallback credit is an Anthropic mechanism that offsets this cost on the retry. The details are documented in the Fallback Credit guide. If your application handles high-volume requests with large cached prompts, this is worth understanding before you implement retry logic.
Learn to Build Production-Ready AI Products
Refusal handling, fallback architecture, and production API integration are covered in the AI PM Masterclass. Taught live by a Salesforce Sr. Director PM.
UX Design for Graceful Degradation
A refusal is a product experience, not just an API event. How your product communicates a refusal to the user determines whether they feel the product is safe and trustworthy or broken and unpredictable.
Silent fallback (best for most cases)
If your fallback model can serve the request, the user never sees the refusal. The fallback result is presented as the normal response. The refusal is an internal implementation detail. Log it for analysis, but do not surface it.
When: Most category types except harmful_content. Use when the request is legitimate and the refusal is a classifier false positive.
Transparent partial refusal
When only part of a multi-part request is refused, acknowledge this. 'I answered questions 1, 2, and 4. I am not able to help with question 3.' This is more trustworthy than silently skipping content.
When: Complex multi-step requests where some steps are refused. Common in research and analysis tools.
Explicit refusal with guidance
Surface the refusal clearly with an explanation of what the model cannot help with and, where possible, an alternative path. 'This request falls outside what I can help with. You might try rephrasing as X or contacting support.'
When: harmful_content category, or when no fallback is available. Also for policy-level refusals where retry will not help.
Category-aware messaging
Different refusal categories warrant different messages. A reasoning_extraction refusal is a product configuration issue. A harmful_content refusal is a user request issue. Do not use the same UX copy for both.
When: Products with diverse use cases and sophisticated users who can act on specific guidance.
Safety-Constrained vs. Unconstrained Models: An Architectural Decision
Claude Fable 5 has safety classifiers. Claude Mythos 5 shares the same capabilities but does not. Mythos 5 is only available through Project Glasswing, Anthropic's limited enterprise access program for approved use cases. This is a meaningful product architectural choice, not just a model selection.
Use Fable 5 (with classifiers) when
- •Your product serves general consumers or broad enterprise users
- •You want Anthropic's safety layer as a default backstop
- •Your use case is mainstream enough that classifiers will not trigger
- •You prefer to handle edge cases in your own application layer
Consider Mythos 5 (without classifiers) when
- •Your use case is in security research, red teaming, or adversarial testing
- •You are building legal, medical, or investigative tools where safety classifiers create false positives
- •You have enterprise approval and your own robust safety infrastructure
- •Classifier false positives are measurably degrading your product quality
Both models have a 30-day data retention requirement and are not available under zero data retention. This is worth noting if your product has data handling requirements that assume zero retention. Check Anthropic's Covered Models documentation for current status.
Product monitoring to add now
Log every refusal event with its category, the request hash (not the full content), and which fallback model was used. After two weeks you will have the data to answer: how often are we being refused, for which category, and are our users affected. This is the baseline you need to make an informed decision about whether refusal handling is a meaningful product quality issue for your specific use case.
Ship AI Products That Work in Production
Handling edge cases, API behaviors, and production failures is what separates AI PMs who ship from AI PMs who demo. The Masterclass covers the full production lifecycle.
Related Articles
Before you go: get the AI PM Minute
One tactic to make you a sharper AI PM, twice a week. 60 seconds to read. Free.
No fluff. Unsubscribe anytime.