12.3 Building "refusal-aware" UX in your app
Overview and links for this section of the guide.
On this page
Why refusal-aware UX matters
In real apps, refusals and blocks are normal. If you treat them as “unexpected errors,” users experience your product as broken.
Refusal-aware UX turns safety behavior into a predictable user journey.
It’s a response state. Your UI should have a designed state for it, like “empty results” or “validation error.”
Treat refusals as an outcome type
In code, represent outcomes explicitly:
- ok: a valid response was produced.
- blocked/refused: content was blocked by safety.
- needs_clarification: ambiguous input; ask a question.
- invalid_output: schema/format failure; retry or fallback.
- timeout/rate_limit: transient failures; retry with backoff.
This makes your UI state machine explicit and keeps failure modes from becoming “generic error.”
User-facing copy that works
Good refusal copy has three parts:
- What happened: “We can’t help with that request.”
- Why (high level): “It may involve unsafe content.”
- What next: rephrase suggestions or safe alternatives.
Keep it calm and helpful. Avoid shaming the user.
Recovery flows (rephrase, clarify, escalate)
Rephrase flow
Offer suggested rephrasings that move the user toward safe intent, such as “high-level explanation” or “safety-focused guidance.”
Clarify flow
If the request is ambiguous, ask a clarifying question rather than refusing immediately. Example: “Are you asking for a general explanation, or instructions?”
Escalation flow (internal tools)
For workplace tools, provide “send to human reviewer” for borderline cases. This keeps the workflow moving without forcing the model to decide alone.
A “Try again” button without guidance trains users to spam retries, which increases cost, rate limits, and frustration. Provide a concrete next step.
Logging and metrics (without leaking data)
Track refusal behavior safely:
- outcome category (ok/blocked/needs_clarification),
- high-level category codes (when available),
- latency, token estimates, retry counts,
- prompt version + model settings.
Avoid logging raw user content unless you have explicit policy and access controls.