SaToken Error Reference

English

Error Categories

sa-token-rust provides 32 error types organized into 10 categories:

1. Basic Token Errors

TokenNotFound

Message: "Token not found or expired"
Description: The requested token does not exist in storage or has expired
Common Causes: Token was never created, expired naturally, or manually deleted
Solution: User needs to log in again to obtain a new token

InvalidToken

Message: "Token is invalid: {reason}"
Description: The token format or content is invalid
Common Causes: Corrupted token, tampered token, or wrong token format
Solution: Verify token integrity and ensure correct token format

TokenExpired

Message: "Token has expired"
Description: The token has passed its expiration time
Common Causes: Token timeout exceeded configured duration
Solution: Use refresh token to get a new access token or re-authenticate

2. Authentication Errors

NotLogin

Message: "User not logged in"
Description: User is attempting to access a protected resource without authentication
Common Causes: No token provided, token not found in request
Solution: User must log in first to obtain a valid token

3. Authorization Errors

PermissionDenied

Message: "Permission denied: missing permission '{permission}'"
Description: User lacks the required permission to perform the action
Common Causes: Insufficient permissions assigned to the user
Solution: Grant the required permission to the user or role

RoleDenied

Message: "Role denied: missing role '{role}'"
Description: User does not have the required role
Common Causes: User not assigned to the necessary role
Solution: Assign the required role to the user

4. Account Status Errors

AccountBanned

Message: "Account is banned until {time}"
Description: The account has been temporarily or permanently banned
Common Causes: Violation of terms, security issues, or administrative action
Solution: Wait until ban expires or contact administrator

AccountKickedOut

Message: "Account is kicked out"
Description: User session has been forcefully terminated
Common Causes: Administrator kicked the user, concurrent login on another device
Solution: User needs to log in again

5. Session Errors

SessionNotFound

Message: "Session not found"
Description: The session does not exist or has been deleted
Common Causes: Session expired, manually deleted, or never created
Solution: Establish a new session by logging in

6. Nonce Errors

NonceAlreadyUsed

Message: "Nonce has been used, possible replay attack detected"
Description: The nonce has already been consumed, indicating a potential replay attack
Common Causes: Duplicate request submission, replay attack attempt
Solution: Generate a new nonce for each request

InvalidNonceFormat

Message: "Invalid nonce format"
Description: The nonce does not follow the expected format
Common Causes: Corrupted nonce, manually crafted invalid nonce
Solution: Use the standard nonce generation method

InvalidNonceTimestamp

Message: "Nonce timestamp is invalid or expired"
Description: The timestamp embedded in the nonce is invalid or outside the valid time window
Common Causes: System time drift, expired nonce, or tampered timestamp
Solution: Synchronize system time and generate a fresh nonce

7. Refresh Token Errors

RefreshTokenNotFound

Message: "Refresh token not found or expired"
Description: The refresh token does not exist or has expired
Common Causes: Never issued, expired, or revoked
Solution: User must re-authenticate to get a new refresh token

RefreshTokenInvalidData

Message: "Invalid refresh token data"
Description: The stored refresh token data is corrupted or malformed
Common Causes: Storage corruption, tampering, or serialization error
Solution: User must re-authenticate

RefreshTokenMissingLoginId

Message: "Missing login_id in refresh token"
Description: The refresh token is missing the required login_id field
Common Causes: Data corruption or incomplete token generation
Solution: Generate a new refresh token

RefreshTokenInvalidExpireTime

Message: "Invalid expire time format in refresh token"
Description: The expiration time in refresh token cannot be parsed
Common Causes: Incorrect date format or corrupted data
Solution: Generate a new refresh token with correct format

8. Token Validation Errors

TokenEmpty

Message: "Token is empty"
Description: No token value provided
Common Causes: Empty string passed as token
Solution: Provide a valid token value

TokenTooShort

Message: "Token is too short"
Description: Token length is below minimum required (8 characters)
Common Causes: Truncated or invalid token
Solution: Provide a complete valid token

LoginIdNotNumber

Message: "Login ID is not a valid number"
Description: Failed to parse login ID as a numeric value
Common Causes: Non-numeric login ID when numeric is expected
Solution: Ensure login ID format matches expected type

9. OAuth2 Errors

OAuth2ClientNotFound

Message: "OAuth2 client not found"
Description: The OAuth2 client ID does not exist
Common Causes: Unregistered client or incorrect client ID
Solution: Register the client or verify client ID

OAuth2InvalidCredentials

Message: "Invalid client credentials"
Description: Client ID and secret combination is invalid
Common Causes: Wrong secret, mistyped credentials
Solution: Verify client credentials are correct

OAuth2ClientIdMismatch

Message: "Client ID mismatch"
Description: Client ID doesn't match the expected value
Common Causes: Using wrong client ID for authorization code or refresh token
Solution: Use the correct client ID that initiated the flow

OAuth2RedirectUriMismatch

Message: "Redirect URI mismatch"
Description: Redirect URI doesn't match registered URIs
Common Causes: URI not in whitelist, typo in URI
Solution: Use a registered redirect URI

OAuth2CodeNotFound

Message: "Authorization code not found or expired"
Description: Authorization code doesn't exist or has expired
Common Causes: Code already used, expired (typically 10 minutes)
Solution: Request a new authorization code

OAuth2AccessTokenNotFound

Message: "Access token not found or expired"
Description: OAuth2 access token not found or expired
Common Causes: Token expired (typically 1 hour), revoked, or never issued
Solution: Refresh token or re-authorize

OAuth2RefreshTokenNotFound

Message: "Refresh token not found or expired"
Description: OAuth2 refresh token not found or expired
Common Causes: Token expired (typically 30 days), revoked, or never issued
Solution: User must re-authorize

OAuth2InvalidRefreshToken

Message: "Invalid refresh token data"
Description: Refresh token data is corrupted or invalid
Common Causes: Data corruption, tampering
Solution: Re-authorize to get new tokens

OAuth2InvalidScope

Message: "Invalid scope data"
Description: Scope data is invalid or corrupted
Common Causes: Invalid scope format, unauthorized scope request
Solution: Request valid scopes only

10. System Errors

StorageError

Message: "Storage error: {details}"
Description: Error occurred while accessing storage backend
Common Causes: Database connection failure, Redis unavailable, network issues
Solution: Check storage backend status and connectivity

ConfigError

Message: "Configuration error: {details}"
Description: Configuration is invalid or missing
Common Causes: Missing required config, invalid config values
Solution: Review and fix configuration

SerializationError

Message: "Serialization error: {details}"
Description: Failed to serialize or deserialize data
Common Causes: Data structure mismatch, corrupted JSON
Solution: Check data format and structure

InternalError

Message: "Internal error: {details}"
Description: An unexpected internal error occurred
Common Causes: Programming error, unexpected state
Solution: Report to developers with error details

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

SaToken Error Reference ​

English ​

Error Categories ​

1. Basic Token Errors ​

TokenNotFound ​

InvalidToken ​

TokenExpired ​

2. Authentication Errors ​

NotLogin ​

3. Authorization Errors ​

PermissionDenied ​

RoleDenied ​

4. Account Status Errors ​

AccountBanned ​

AccountKickedOut ​

5. Session Errors ​

SessionNotFound ​

6. Nonce Errors ​

NonceAlreadyUsed ​

InvalidNonceFormat ​

InvalidNonceTimestamp ​

7. Refresh Token Errors ​

RefreshTokenNotFound ​

RefreshTokenInvalidData ​

RefreshTokenMissingLoginId ​

RefreshTokenInvalidExpireTime ​

8. Token Validation Errors ​

TokenEmpty ​

TokenTooShort ​

LoginIdNotNumber ​

9. OAuth2 Errors ​

OAuth2ClientNotFound ​

OAuth2InvalidCredentials ​

OAuth2ClientIdMismatch ​

OAuth2RedirectUriMismatch ​

OAuth2CodeNotFound ​

OAuth2AccessTokenNotFound ​

OAuth2RefreshTokenNotFound ​

OAuth2InvalidRefreshToken ​

OAuth2InvalidScope ​

10. System Errors ​

StorageError ​

ConfigError ​

SerializationError ​

InternalError ​

Summary | 总结 ​