Enum WeChatError 

pub enum WeChatError {
    Configuration(String),
    Transport(TransportError),
    ResponseParseFailed {
        url: String,
        error: String,
        preview: String,
    },
    ApiError {
        errcode: i32,
        errmsg: String,
    },
    AccessTokenExpired {
        code: i32,
    },
    AccessTokenMissing,
    TokenInvalidated,
    InvalidCode,
    CodeUsed,
    CodeExpired,
    RefreshTokenInvalid,
    RefreshTokenExpired,
    UserUnauthorized,
    RateLimitExceeded {
        code: i32,
        msg: String,
    },
    IpNotWhitelisted,
    SystemBusy,
    InvalidParameter(String),
    HttpBuildError(String),
}

微信授权错误类型

Variants

Configuration(String)

配置错误

Transport(TransportError)

网络传输错误

ResponseParseFailed

响应解析失败

Fields

url: String

error: String

preview: String

ApiError

微信API通用错误

Fields

errcode: i32

errmsg: String

AccessTokenExpired

Access Token过期或无效

错误码: 40001, 40014, 42001

解决方案:

1. 检查AppSecret是否正确
2. 使用refresh_token刷新access_token
3. 如果refresh_token也过期,需要重新授权

Fields

code: i32

AccessTokenMissing

Access Token缺失

错误码: 41001

解决方案: 检查API调用时是否传递了access_token参数

TokenInvalidated

用户修改密码导致Token失效

错误码: 42007

原因: 用户修改了微信密码,导致之前授权的所有token失效

解决方案: 引导用户重新进行授权

InvalidCode

无效的授权码

错误码: 40029

原因:

• 授权码格式错误
• 授权码不是通过微信授权流程获得
• AppID与授权码不匹配

解决方案: 检查授权流程是否正确,确保使用正确的AppID

CodeUsed

授权码已被使用

错误码: 40163

原因:

• 授权码(code)只能使用一次
• 页面刷新或重复请求导致code被重复使用
• 服务端错误导致回调接口被调用多次

解决方案:

1. 检查前端是否有重复请求
2. 确保回调接口没有抛出异常
3. 避免页面刷新时重复使用旧的code
4. 让用户重新进行授权获取新的code

CodeExpired

授权码已过期

错误码: 42003

原因: 授权码(code)的有效期为5分钟,超时后无法使用

解决方案: 引导用户重新进行授权获取新的code

RefreshTokenInvalid

Refresh Token无效

错误码: 40030

解决方案: 引导用户重新授权

RefreshTokenExpired

Refresh Token已过期

错误码: 42002

原因: refresh_token的有效期为30天,超时后无法使用

解决方案: 引导用户重新进行授权

UserUnauthorized

用户未授权该API

错误码: 50001

原因:

• 授权作用域不足
• 账号类型不支持该API
• 未配置授权回调域名

解决方案:

1. 检查授权时的scope参数
2. 确认账号类型是否支持(如需要认证的服务号)
3. 在微信后台配置授权回调域名

RateLimitExceeded

API调用频率超限

错误码: 45009(分钟级), 45011(日级)

解决方案:

1. 实施请求限流
2. 使用缓存减少API调用
3. 等待限制解除后重试

Fields

code: i32

msg: String

IpNotWhitelisted

服务器IP未在白名单中

错误码: 40164

解决方案: 在微信公众平台后台添加服务器IP到白名单

SystemBusy

微信系统繁忙

错误码: -1

解决方案: 这是临时性错误,等待后重试即可

InvalidParameter(String)

参数错误

错误码: 61451

解决方案: 检查API调用参数是否正确

HttpBuildError(String)

HTTP构建错误

Implementations

impl WeChatError

pub fn is_retriable(&self) -> bool

判断错误是否可以重试

返回值

• true: 错误是临时性的,可以重试
• false: 错误需要人工介入,重试无效

示例

if error.is_retriable() {
    // 等待后重试
    println!("可以重试");
} else {
    println!("无法重试,需要人工处理");
}

pub fn requires_reauthorization(&self) -> bool

判断错误是否需要重新授权

返回值

• true: 需要引导用户重新进行微信授权
• false: 不需要重新授权

示例

if error.requires_reauthorization() {
    // 清除本地token缓存
    // 返回授权URL给前端
    println!("需要重新授权");
}

pub fn is_configuration_error(&self) -> bool

判断错误是否是配置问题

返回值

• true: 是配置问题,需要修改配置
• false: 不是配置问题

示例

if error.is_configuration_error() {
    // 记录配置错误日志
    // 发送告警通知
    eprintln!("配置错误: {}", error);
}

pub fn recommended_retry_delay(&self) -> Option<u64>

获取错误的推荐重试延迟(秒)

返回值

• Some(seconds): 建议延迟的秒数
• None: 不建议重试

示例

if let Some(delay) = error.recommended_retry_delay() {
    println!("建议{}秒后重试", delay);
    // tokio::time::sleep(Duration::from_secs(delay)).await;
}

Trait Implementations

impl Debug for WeChatError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for WeChatError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for WeChatError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for WeChatError

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<TransportError> for WeChatError

fn from(source: TransportError) -> Self

Converts to this type from the input type.