Feyra API 错误码规范（Single Source of Truth）
本文档是 Feyra API
错误码的唯一权威来源（SSOT）。所有业务异常必须使用下表中的常量值，
禁止在代码中手写字符串（如
"INVALID_ARGUMENT"）。
📌 使用说明：
-
前端通过
error.details[0].reason
获取错误码，用于精准判断错误类型（如
switch(reason)）。
-
后端抛出异常时，必须使用
Reason.INVALID_ARGUMENT 等常量（来自
app.core.exceptions.Reason）。
-
新增错误码时
必须同步更新此页面、design_error_handling.md和代码中的
Reason 枚举/常量类。
详细设计请参考：
wiki/design/feyra-api/design_error_handling.md
400 Bad Request：客户端参数/语法错误
| 错误码（reason） |
说明 |
INVALID_ARGUMENT |
通用无效参数（如 missing/类型错误） |
INVALID_SORT_OPTION |
不支持的排序方案 |
INVALID_PAGINATION_TOKEN |
分页令牌无效或已过期 |
INVALID_DATETIME_FORMAT |
时间格式不符合 ISO 8601 标准 |
401 Unauthorized：认证失败
| 错误码（reason） |
说明 |
AUTH_TOKEN_MISSING |
请求缺少认证令牌（如 JWT） |
AUTH_TOKEN_INVALID |
认证令牌无效（如签名错误、已过期） |
AUTH_TOKEN_REVOKED |
Token 已被加入黑名单（如用户主动登出、管理员强制失效） |
AUTH_TOKEN_MALFORMED |
Token 格式错误(荷载无效) |
AUTH_USER_NOT_FOUND |
Token 关联的用户不存在 |
403 Forbidden：权限不足
| 错误码（reason） |
说明 |
ACCESS_DENIED |
用户无权访问该资源或执行该操作 |
USER_ACCOUNT_DISABLED |
用户账户已被禁用 |
404 Not Found：业务资源不存在
| 错误码（reason） |
说明 |
RESOURCE_NOT_FOUND |
开发者主动抛出：指定业务资源不存在（如用户ID无效） |
409 Conflict：资源冲突
| 错误码（reason） |
说明 |
USER_EMAIL_EXISTS |
用户邮箱已存在（注册冲突） |
422 Unprocessable Entity：业务规则校验失败
| 错误码（reason） |
说明 |
FAILED_PRECONDITION |
前置条件不满足（如账户已禁用，无法进行后续操作） |
框架自动抛出的错误（非业务代码使用）
| 错误码（reason） |
说明 |
HTTP_404 |
请求路径不存在（FastAPI 自动返回） |
HTTP_405 |
HTTP 方法不支持（如 POST 到只支持 GET 的路由） |
500 Internal Server Error：系统错误
| 错误码（reason） |
说明 |
INTERNAL_ERROR |
仅由全局异常中间件使用，表示未预期的服务器内部错误 |
⚠️ 重要提醒：
任何新增的业务错误类型，都必须：
- 在代码中定义新的
Reason.XXX 常量；
- 同步更新本页面，确保前后端认知一致；
- 在设计文档中说明使用场景。