错误参考

中文

错误分类

sa-token-rust 提供了 32 种错误类型，分为 10 个类别：

1. 基础 Token 错误

TokenNotFound

• 消息：Token 未找到或已过期
• 描述：请求的 Token 在存储中不存在或已过期
• 常见原因：Token 从未创建、自然过期或被手动删除
• 解决方案：用户需要重新登录以获取新的 Token

InvalidToken

• 消息：Token 无效：
• 描述：Token 格式或内容无效
• 常见原因：Token 损坏、被篡改或格式错误
• 解决方案：验证 Token 完整性并确保格式正确

TokenExpired

• 消息：Token 已过期
• 描述：Token 已超过其有效期
• 常见原因：Token 超时超过配置的持续时间
• 解决方案：使用刷新令牌获取新的访问令牌或重新认证

2. 认证错误

NotLogin

• 消息：用户未登录
• 描述：用户试图在未认证的情况下访问受保护的资源
• 常见原因：未提供 Token，请求中找不到 Token
• 解决方案：用户必须先登录以获取有效的 Token

3. 授权错误

PermissionDenied

• 消息：权限被拒绝：缺少权限 '{权限}'
• 描述：用户缺少执行该操作所需的权限
• 常见原因：用户权限不足
• 解决方案：为用户或角色授予所需权限

RoleDenied

• 消息：角色被拒绝：缺少角色 '{角色}'
• 描述：用户没有所需的角色
• 常见原因：用户未被分配到必要的角色
• 解决方案：为用户分配所需角色

4. 账户状态错误

AccountBanned

• 消息：账户被封禁至
• 描述：账户已被临时或永久封禁
• 常见原因：违反条款、安全问题或管理员操作
• 解决方案：等待封禁到期或联系管理员

AccountKickedOut

• 消息：账户被踢出
• 描述：用户会话已被强制终止
• 常见原因：管理员踢出用户、在其他设备上并发登录
• 解决方案：用户需要重新登录

5. Session 错误

SessionNotFound

• 消息：Session 未找到
• 描述：会话不存在或已被删除
• 常见原因：会话过期、被手动删除或从未创建
• 解决方案：通过登录建立新会话

6. Nonce 错误

NonceAlreadyUsed

• 消息：Nonce 已被使用，可能检测到重放攻击
• 描述：Nonce 已被消费，表明可能存在重放攻击
• 常见原因：重复提交请求、重放攻击尝试
• 解决方案：为每个请求生成新的 Nonce

InvalidNonceFormat

• 消息：无效的 Nonce 格式
• 描述：Nonce 不符合预期格式
• 常见原因：Nonce 损坏、手动构造的无效 Nonce
• 解决方案：使用标准的 Nonce 生成方法

InvalidNonceTimestamp

• 消息：Nonce 时间戳无效或已过期
• 描述：Nonce 中嵌入的时间戳无效或超出有效时间窗口
• 常见原因：系统时间偏移、Nonce 过期或时间戳被篡改
• 解决方案：同步系统时间并生成新的 Nonce

7. 刷新令牌错误

RefreshTokenNotFound

• 消息：刷新令牌未找到或已过期
• 描述：刷新令牌不存在或已过期
• 常见原因：从未发行、已过期或已撤销
• 解决方案：用户必须重新认证以获取新的刷新令牌

RefreshTokenInvalidData

• 消息：无效的刷新令牌数据
• 描述：存储的刷新令牌数据已损坏或格式错误
• 常见原因：存储损坏、篡改或序列化错误
• 解决方案：用户必须重新认证

RefreshTokenMissingLoginId

• 消息：刷新令牌中缺少 login_id
• 描述：刷新令牌缺少必需的 login_id 字段
• 常见原因：数据损坏或令牌生成不完整
• 解决方案：生成新的刷新令牌

RefreshTokenInvalidExpireTime

• 消息：刷新令牌中的过期时间格式无效
• 描述：刷新令牌中的过期时间无法解析
• 常见原因：日期格式不正确或数据损坏
• 解决方案：生成格式正确的新刷新令牌

8. Token 验证错误

TokenEmpty

• 消息：Token 为空
• 描述：未提供 Token 值
• 常见原因：传递了空字符串作为 Token
• 解决方案：提供有效的 Token 值

TokenTooShort

• 消息：Token 太短
• 描述：Token 长度低于最小要求（8 个字符）
• 常见原因：被截断或无效的 Token
• 解决方案：提供完整有效的 Token

LoginIdNotNumber

• 消息：登录 ID 不是有效数字
• 描述：无法将登录 ID 解析为数值
• 常见原因：当期望数字时提供了非数字登录 ID
• 解决方案：确保登录 ID 格式与预期类型匹配

9. OAuth2 错误

OAuth2ClientNotFound

• 消息：OAuth2 客户端未找到
• 描述：OAuth2 客户端 ID 不存在
• 常见原因：未注册的客户端或客户端 ID 错误
• 解决方案：注册客户端或验证客户端 ID

OAuth2InvalidCredentials

• 消息：无效的客户端凭据
• 描述：客户端 ID 和密钥组合无效
• 常见原因：密钥错误、凭据输入错误
• 解决方案：验证客户端凭据是否正确

OAuth2ClientIdMismatch

• 消息：客户端 ID 不匹配
• 描述：客户端 ID 与预期值不匹配
• 常见原因：为授权码或刷新令牌使用了错误的客户端 ID
• 解决方案：使用发起流程的正确客户端 ID

OAuth2RedirectUriMismatch

• 消息：重定向 URI 不匹配
• 描述：重定向 URI 与注册的 URI 不匹配
• 常见原因：URI 不在白名单中、URI 拼写错误
• 解决方案：使用已注册的重定向 URI

OAuth2CodeNotFound

• 消息：授权码未找到或已过期
• 描述：授权码不存在或已过期
• 常见原因：授权码已使用、已过期（通常 10 分钟）
• 解决方案：请求新的授权码

OAuth2AccessTokenNotFound

• 消息：访问令牌未找到或已过期
• 描述：OAuth2 访问令牌未找到或已过期
• 常见原因：令牌过期（通常 1 小时）、已撤销或从未发行
• 解决方案：刷新令牌或重新授权

OAuth2RefreshTokenNotFound

• 消息：刷新令牌未找到或已过期
• 描述：OAuth2 刷新令牌未找到或已过期
• 常见原因：令牌过期（通常 30 天）、已撤销或从未发行
• 解决方案：用户必须重新授权

OAuth2InvalidRefreshToken

• 消息：无效的刷新令牌数据
• 描述：刷新令牌数据已损坏或无效
• 常见原因：数据损坏、篡改
• 解决方案：重新授权以获取新令牌

OAuth2InvalidScope

• 消息：无效的权限范围数据
• 描述：权限范围数据无效或已损坏
• 常见原因：权限范围格式无效、未授权的权限范围请求
• 解决方案：仅请求有效的权限范围

10. 系统错误

StorageError

• 消息：存储错误：
• 描述：访问存储后端时发生错误
• 常见原因：数据库连接失败、Redis 不可用、网络问题
• 解决方案：检查存储后端状态和连接性

ConfigError

• 消息：配置错误：
• 描述：配置无效或缺失
• 常见原因：缺少必需配置、配置值无效
• 解决方案：审查并修复配置

SerializationError

• 消息：序列化错误：
• 描述：序列化或反序列化数据失败
• 常见原因：数据结构不匹配、JSON 损坏
• 解决方案：检查数据格式和结构

InternalError

• 消息：内部错误：
• 描述：发生意外的内部错误
• 常见原因：编程错误、意外状态
• 解决方案：向开发人员报告错误详情

---

Summary | 总结

This document provides comprehensive error documentation in Chinese and English for sa-token-rust. Each error includes:

• Error message
• Detailed description
• Common causes
• Solutions

For developers integrating sa-token-rust, this guide helps understand and handle errors effectively.

---

Version: 0.1.14
Last Updated: 2026-05-07