Problem it solves
Products surface generic error messages for AI failures, giving users no actionable information about what went wrong or how to recover.
When to use
Whenever a model returns an error, refusal, or failed generation. Applies to all model-facing interfaces.
When not to use
For system-level or network errors unrelated to the model. Those follow standard error conventions.
Governing principle
AI errors are typed. The UI must surface the specific error type, a human-readable cause, and at least one concrete recovery action matched to that type.
Required Components
Interaction Flow
Model returns an error
The error type is identified: hallucination, refusal, rate limit, timeout, or context overflow.
Error surface activates
The AI Error States component surfaces the typed error with a human-readable explanation.
Recovery action presented
At least one concrete recovery action is shown: retry, rephrase, escalate, or contact support — specific to the error type.
User chooses recovery path
The user selects an action. If the error requires operator attention, an escalation path is available.
Recovery attempt or escalation
The selected action is executed. If the retry fails, a secondary recovery path is offered.
Governance requirements
Error events must be logged with type, timestamp, and the recovery action taken. Repeated errors of the same type should surface escalation options earlier.
Accessibility notes
Error states must use role="alert" to ensure immediate announcement. Error messages must be meaningful in isolation — not just "An error occurred." Recovery actions must be keyboard accessible.