Claude API refusal handling

Start with a refusal state machine

The Messages API exposes different ways a response can end. A normal completion, a tool-use turn, a pause, max-token truncation, context-window overflow, and a refusal do not mean the same thing. Treating them all as one generic failure makes the product harder to debug and can create unsafe retry behavior.

A practical state machine starts with the stop reason, then routes to one of four outcomes: show the answer, continue the tool loop, repair the request budget, or present a refusal-safe alternative. That routing should be visible in logs and analytics so overrefusal, policy hits, and context failures can be measured separately.

• Refusal: show a clear boundary, preserve user context, and offer a safe alternative when one exists.
• Max tokens: continue, summarize, or split the output instead of rewriting the safety boundary.
• Tool use or pause: continue the permitted tool workflow and verify tool results.
• Context overflow: trim, summarize, or reattach source material before retrying.

Log the observable boundary

Useful refusal logs do not need to store sensitive prompt text. They should record model ID, surface, prompt template version, stop reason, policy category if available, whether the user was offered a safe alternative, and whether a human override or support path was used. This lets a team tell the difference between one bad prompt, a product regression, and a broad refusal-pattern change.

Do not use successful completion as proof that the request was safe or correct. The refusal handler belongs next to source verification, high-stakes review, and tool-call validation. A non-refusal can still hallucinate, misread a source, or exceed the intended authority level.

Recover without evasion

A good recovery path explains the boundary in plain language and asks for missing legitimate context: authorization, defensive purpose, audience, jurisdiction, or desired exclusions. It does not tell users to disguise intent, ignore policy, or convert a disallowed request into a coded version of the same request.

For customer-facing products, pair the refusal with a next step. That might be a safer educational explanation, a template for supplying authorized context, a human-review handoff, or a note that the product cannot support the requested action. The key is to make the refusal useful without weakening the boundary.