Error and Exception Design

Template Library

Error and Exception Design Template

Define expected behavior when validation fails, access is denied, state transitions are invalid, evidence is missing, AI fails, or external services are unavailable.

ES-105 Failure Design Safe Behavior

Library AreaTemplate Library

Current PageError and Exception Design

FocusFailure behavior

UseDefine errors, exceptions, escalation, and evidence

Repository Areadocs/template-library/design/

← Previous AI Interaction Design

Current Error and Exception Design

Next → Technical Decision Records

Template purpose

Use this template to design how the system behaves when something goes wrong.

Failure behavior should be explicit before implementation begins. A trustworthy system should fail visibly, safely, and with evidence.

Project

<Project name>

Document control

Field	Value
Artifact owner	<owner>
Primary reviewers	<reviewers>
Status	<draft / in review / accepted / revised>
Last updated	<YYYY-MM-DD>
Related Engineering Stage	ES-105 — Detailed Design
Project workspace target	docs/project-workspace/design/error_and_exception_design.md

Error / exception register

ID	Scenario	Expected Behavior	User Message / Response	Evidence / Log	Related Requirement
ERR-001	<scenario>	<behavior>	<message/response>	<evidence>	<requirement>

Error categories

Category	Examples	General Response
Validation error	<examples>	<response>
Authorization error	<examples>	<response>
Invalid state transition	<examples>	<response>
Missing evidence	<examples>	<response>
AI failure	<examples>	<response or not applicable>
External service failure	<examples>	<response>
Data integrity issue	<examples>	<response>
Operational failure	<examples>	<response>

Access denied behavior

<behavior>

Invalid state transition behavior

<behavior>

Missing evidence behavior

<behavior>

AI failure behavior

<behavior or "AI is not used.">

External service failure behavior

<behavior>

Retry, fallback, and stop rules

Scenario	Retry?	Fallback?	Stop / Escalate?
<scenario>	<yes/no/rule>	<fallback>	<stop or escalation rule>

User communication

Scenario	Message Principle	Example
<scenario>	<clear, non-blaming, actionable, not over-revealing>	<example>

Evidence and audit behavior

Scenario	Evidence Produced	Retention / Review
<scenario>	<log, event, incident record, review note, alert>	<rule>

Operational escalation

Scenario	Escalate To	Trigger
<scenario>	<role/team>	<trigger>

Open failure-design questions

ID	Question	Owner	Needed By
EDQ-001	<question>	<owner>	<date or stage>

Review checklist

• [ ] Major error scenarios are listed.
• [ ] Access denied behavior is defined.
• [ ] Invalid state transitions are handled.
• [ ] Missing evidence behavior is defined.
• [ ] AI failure behavior is defined or marked not applicable.
• [ ] External service failure behavior is defined.
• [ ] Retry, fallback, stop, and escalation rules are stated.
• [ ] Evidence and audit behavior are defined.

Continue to Technical Decision Records

Record detailed design decisions, alternatives, rationale, tradeoffs, and verification impacts.

Open Technical Decision Records →