用途：统一全栈错误分类，让每个错误都有错误码、类别、严重级别和面向用户的消息，衔接 FastAPI 的 ErrorResponse 模型与 Next.js 的 ApiClientError 类。
主要能力：错误码采用 {DOMAIN}{CATEGORY}{SPECIFIC} 格式，如 AUTH_VALIDATION_INVALID_TOKEN、AGENT_RUNTIME_TIMEOUT、DATA_VALIDATION_MISSING_FIELD。域包括 AUTH_（登录、JWT、权限）、AGENT_（智能体执行、LLM 提供方）、DATA_（校验、转换、存储）、WORKFLOW_（流水线、状态机、调度）、SYS_（基础设施、数据库、外部服务）。类别包括 Validation、Runtime、Permission、NotFound、Conflict、RateLimit、External。严重级别分 Fatal（500-599，记录并告警升级）、Error（400-499，记录并返回用户消息）、Warning（200 带警告头，仅记录）。
使用方式：后端扩展 ErrorResponse 模型（含 detail、error_code、severity、field），抛出 HTTPException 时传入结构化错误；注册全局校验异常处理器，把 Pydantic ValidationError 转为结构化响应。前端扩展 ApiError 与 ApiClientError（含 severity、field，以及 isAuth、isValidation、isRetryable 判断），并用 ERROR_MESSAGES 映射表把错误码转为用户可读消息。新增错误码需选域、选类别、加具体标识，登记到错误码注册表，并在前端映射用户消息。
适用场景：创建或修改 API 错误响应、在 FastAPI 路由新增 HTTPException、实现前端错误处理或展示、设计 React 错误边界、审查前后端错误一致性。
限制：不适用于重试/弹性逻辑（用 retry-strategy）、React 错误边界组件设计（用 error-boundary），也不处理构建、lint 或类型错误。资料还提到 API 契约要求每个端点记录可能的错误码，破坏性错误码变更需版本升级，以及 en-AU 本地化约定（日期 DD/MM/YYYY、货币 AUD、拼写 colour/behaviour/optimisation 等）。