error-codes.md

错误码手册 (Error Codes)

错误码结构: {段位}-{模块}-{序号}，如 E-AUTH-1002。 用户可见错误均为三段式: 人话 + 错误码 + 排查文档链接。 查询全部错误码: GET /api/v1/text/error-codes

错误码表

错误码	HTTP	消息模板	触发条件	排查指引
E-AUTH-1001	401	邮箱或密码错误	登录时账号不存在或密码错误	检查邮箱/重置密码
E-AUTH-1002	423	登录尝试过多，账号已临时锁定	连续失败达阈值	等待解锁或管理员解锁
E-AUTH-1003	403	需要双因子验证	已启用 MFA 未携带 OTP	携带 otp 重新登录
E-AUTH-1004	401	双因子验证码错误	OTP 错误/过期	重新获取 TOTP
E-AUTH-1005	403	管理员必须启用 MFA 后才能登录	MFA_ENFORCE_ADMIN=true	先绑定 MFA
E-PERM-2001	403	无权执行该操作	角色无权访问	检查角色/租户
E-VALID-3001	422	参数校验失败	请求参数不合法	修正请求体
E-VALID-3002	422	输出结构校验失败	结构化输出未过校验	检查 schema
E-LLM-4001	502	模型调用失败	LLM 返回错误/超时	检查模型配置
E-LLM-4002	503	模型未配置或不可用	无可用 Provider	配置 API Key
E-TOOL-5001	502	工具执行失败	工具抛异常	检查工具参数
E-TOOL-5002	404	工具不存在	调用了未注册工具	检查工具名
E-RAG-6001	502	知识库检索失败	向量库异常	检查向量库
E-TASK-7001	400	任务状态流转不合法	状态机非法跳转	检查流转路径
E-SYS-8001	500	系统内部错误	未分类异常	查看日志
E-SYS-8002	501	功能未实现或依赖缺失	依赖库未安装	按提示安装
E-NET-9001	502	网络请求失败	外部调用失败	检查网络

使用

from core.errors import AppError

raise AppError("E-VALID-3002", "输出结构校验失败")
exc = AppError("E-TOOL-5002")
http = exc.to_http_exception()  # HTTPException