Editing Troubleshooting of Claude (section)

=== How to fix "stop_reason": "refusal" in Claude API ===

'''Error message'''
<pre>
{
    "id": "msg_xxx",
    "type": "message",
    "role": "assistant",
    "model": "claude-opus-4-20250514",
    "content": [],
    "stop_reason": "refusal",
    "stop_sequence": null,
    "usage": {
        "input_tokens": 2164,
        "cache_creation_input_tokens": 0,
        "cache_read_input_tokens": 0,
        "output_tokens": 0
    }
}
</pre>

'''Model Affected''': Claude Opus 4

'''Suggestion'''

Prompt met "refusal" error
<pre>
Please help find the company's unified business number:
Company name: {$companyName}
</pre>

Revised prompt:
<pre>
Please help find the following company's publicly available basic information: the company's unified business number:
Company name: {COMPANY_NAME}
</pre>

'''Root cause:''' Common Triggers:
* Privacy-related requests - asking for personal data or private information
* Confidential information queries - requesting internal data or business secrets
* Security-sensitive content - potentially harmful or inappropriate requests
* Ambiguous identity information - queries that may involve identity identification

'''Suggested:'''
* Replace sensitive keywords in your prompts (e.g., "confidential" → "public", "internal data" → "public documents", "private information" → "publicly available information")
* Add safety declarations explicitly stating you only want publicly available information
* Use structured prompts that specify data source limitations and public nature requirements
* Implement the smart retry mechanism with prompt modification when refusal is detected
* Consider using the `RefusalPreventionHelper` class to assess and sanitize prompts before sending to API

'''Official Documentation:'''
* [https://docs.anthropic.com/en/api/handling-stop-reasons Handling stop reasons - Anthropic] mentioned "Claude’s response includes a stop_reason field that indicates why the model stopped generating its response ..."
* [https://www.anthropic.com/transparency Anthropic’s Transparency Hub \ Anthropic]
* [https://www.anthropic.com/news/activating-asl3-protections Activating AI Safety Level 3 Protections \ Anthropic]
* [https://support.anthropic.com/en/articles/8241216-i-m-planning-to-launch-a-product-using-claude-what-steps-should-i-take-to-ensure-i-m-not-violating-anthropic-s-usage-policy I’m planning to launch a product using Claude. What steps should I take to ensure I’m not violating Anthropic’s Usage Policy? | Anthropic Help Center]