AI error states are handled with clear user messaging
Why it matters
AI API calls fail in distinct ways: rate limits (429), network drops, content policy blocks, and model-level errors. When these surface as a blank message, a raw JSON dump, or a generic toast with no retry path, users blame the product — not the underlying API. Per iso-25010:2011 reliability.fault-tolerance, the system must degrade gracefully. A rate-limit error that tells the user to wait 60 seconds retains trust; a silent failure causes churn. Distinguishing at least two error types is the minimum required to make error messaging actionable rather than decorative.
Severity rationale
High because undifferentiated error states leave users stranded — they cannot determine whether to retry, wait, rephrase, or escalate — directly degrading retention and support load.
Remediation
Replace catch-all error handling with a typed error classifier that produces distinct messages for rate limits, network failures, and content policy blocks. Render the message inline in the conversation thread, not as a dismissible toast.
const getErrorMessage = (error: Error): string => {
if (error.message.includes('429') || error.message.includes('rate limit'))
return "Rate limit reached — wait a moment and try again."
if (error.message.includes('content_policy'))
return "Response blocked by content policy. Try rephrasing."
if (error.message.includes('fetch') || error.message.includes('network'))
return "Connection issue — check your internet and retry."
return "Generation failed. Try again or regenerate."
}
{error && (
<div className="flex gap-2 p-3 rounded-lg bg-destructive/10 text-destructive text-sm">
<AlertCircleIcon className="w-4 h-4 mt-0.5 shrink-0" />
<span>{getErrorMessage(error)} <button onClick={reload} className="underline">Retry</button></span>
</div>
)}
DetectionPro
The detection method for this pattern is part of AuditBuffet Pro.
The full method (what to look for, pass and fail conditions, and how results get reported) ships inside the AI UX Patterns Audit. The pattern definition, severity rationale, and remediation remain openly licensed under CC-BY-4.0.
External references
- iso-25010:2011 · reliability.fault-tolerance — Fault Tolerance — system operates as intended when AI API errors occur
Taxons
History
- 2026-04-18·v1.0.0·Initial import from ai-ux-patterns·automated