wechat_minapp/
error.rs

1//! 微信小程序错误处理模块
2//!
3//! 该模块定义了与微信小程序 API 交互过程中可能遇到的所有错误类型，
4//! 包括微信官方错误码映射和第三方库错误转换。
5//!
6//! # 错误类型
7//!
8//! 模块包含两种主要的错误类型：
9//!
10//! - [`Error`][]: 主要的错误枚举，包含所有可能的错误情况
11//! - [`ErrorCode`]: 微信官方错误码的 Rust 枚举表示
12//!
13//!
14//! // 处理网络错误
15//! async fn make_api_request() -> Result<(), Error> {
16//!     let client = reqwest::Client::new();
17//!     let response = client.get("https://api.weixin.qq.com/some/endpoint")
18//!         .send()
19//!         .await?; // 自动转换为 Error::Reqwest
20//!     Ok(())
21//! }
22//! ```
23//!
24//! # 错误转换
25//!
26//! 模块自动实现了从常见第三方库错误到 [`Error`] 的转换：
27//!
28//! - `reqwest::Error` → `Error::Reqwest`
29//! - `serde_json::Error` → `Error::SerdeJson`
30//! - `base64::DecodeError` → `Error::Base64Decode`
31//! - `aes::cipher::InvalidLength` → `Error::AesInvalidLength`
32//!
33//! 这使得错误处理更加方便，可以使用 `?` 操作符自动转换。
34
35use serde_repr::Deserialize_repr;
36
37use aes::cipher::InvalidLength as AesInvalidLength;
38use aes::cipher::block_padding::UnpadError;
39use base64::DecodeError as Base64DecodeError;
40use reqwest::Error as ReqwestError;
41use serde_json::Error as SerdeJsonError;
42use strum::Display;
43
44/// 微信小程序 SDK 错误枚举
45///
46/// 包含了所有可能遇到的错误类型，包括微信 API 错误、网络错误、加解密错误等。
47///
48/// # 错误分类
49///
50/// ## 微信 API 错误
51///
52/// 这些错误对应微信官方文档中的错误码：
53///
54/// - `InvalidCredential`: 凭证无效
55/// - `InvalidCode`: 登录 code 无效
56/// - `RateLimitExceeded`: API 调用频率限制
57/// - 等等...
58///
59/// ## 第三方库错误
60///
61/// 自动转换的第三方库错误：
62///
63/// - `Reqwest`: HTTP 请求错误
64/// - `SerdeJson`: JSON 序列化/反序列化错误
65/// - `Base64Decode`: Base64 解码错误
66/// - `AesInvalidLength`: AES 加解密长度错误
67///
68/// ## 系统错误
69///
70/// - `System`: 微信系统繁忙
71/// - `InternalServer`: 内部服务器错误
72///
73///
74/// # 序列化
75///
76/// 此枚举使用 `thiserror` 派生宏，提供了良好的错误消息格式。
77/// 每个变体都包含描述性的错误信息。
78#[non_exhaustive]
79#[derive(Debug, thiserror::Error)]
80pub enum Error {
81    /// 微信系统繁忙，请稍候再试
82    #[error("system error: {0}")]
83    System(String),
84
85    /// 获取 access_token 时 AppSecret 错误，或者 access_token 无效
86    #[error("invalid credential: {0}")]
87    InvalidCredential(String),
88
89    /// 不合法的凭证类型
90    #[error("invalid grant type: {0}")]
91    InvalidGrantType(String),
92
93    /// 不合法的 AppID，请检查 AppID 的正确性
94    #[error("invalid app id: {0}")]
95    InvalidAppId(String),
96
97    /// 登录 code 无效或已过期
98    #[error("invalid code: {0}")]
99    InvalidCode(String),
100
101    /// 请求参数错误
102    #[error("invalid parameter: {0}")]
103    InvalidParameter(String),
104
105    /// 无效的 appsecret，请检查 appsecret 的正确性
106    #[error("invalid secret: {0}")]
107    InvalidSecret(String),
108
109    /// IP 地址不在白名单中
110    #[error("forbidden ip: {0}")]
111    ForbiddenIp(String),
112
113    /// 高风险等级用户，小程序登录被拦截
114    #[error("code blocked: {0}")]
115    CodeBlocked(String),
116
117    /// AppSecret 已被冻结，请登录小程序平台解冻
118    #[error("secret frozen: {0}")]
119    SecretFrozen(String),
120
121    /// 缺少 access_token 参数
122    #[error("missing access token: {0}")]
123    MissingAccessToken(String),
124
125    /// 缺少 appid 参数
126    #[error("missing app id: {0}")]
127    MissingAppId(String),
128
129    /// 缺少 secret 参数
130    #[error("missing secret: {0}")]
131    MissingSecret(String),
132
133    /// 缺少 code 参数
134    #[error("missing code: {0}")]
135    MissingCode(String),
136
137    /// 需要 POST 请求
138    #[error("required post method: {0}")]
139    RequiredPostMethod(String),
140
141    /// 调用超过天级别频率限制
142    #[error("daily request limit exceeded: {0}")]
143    DailyRequestLimitExceeded(String),
144
145    /// API 调用太频繁，请稍候再试
146    #[error("rate limit exceeded: {0}")]
147    RateLimitExceeded(String),
148
149    /// 禁止使用 token 接口
150    #[error("forbidden token: {0}")]
151    ForbiddenToken(String),
152
153    /// 账号已冻结
154    #[error("account frozen: {0}")]
155    AccountFrozen(String),
156
157    /// 第三方平台 API 需要使用第三方平台专用 token
158    #[error("third party token: {0}")]
159    ThirdPartyToken(String),
160
161    /// session_key 不存在或已过期
162    #[error("session key not existed or expired: {0}")]
163    SessionKeyNotExistedOrExpired(String),
164
165    /// 无效的签名方法
166    #[error("invalid signature method: {0}")]
167    InvalidSignatureMethod(String),
168
169    /// 无效的签名
170    #[error("invalid signature: {0}")]
171    InvalidSignature(String),
172
173    /// 此次调用需要管理员确认，请耐心等候
174    #[error("confirm required: {0}")]
175    ConfirmRequired(String),
176
177    /// 该IP调用请求已被公众号管理员拒绝，请24小时后再试
178    #[error("request denied one day: {0}")]
179    RequestDeniedOneDay(String),
180
181    /// 该IP调用请求已被公众号管理员拒绝，请1小时后再试
182    #[error("request denied one hour: {0}")]
183    RequestDeniedOneHour(String),
184
185    /// AES 解密时数据填充错误
186    #[error("unpad error: {0}")]
187    Unpad(UnpadError),
188
189    /// AES 加解密长度错误
190    #[error("aes invalid length: {0}")]
191    AesInvalidLength(#[from] AesInvalidLength),
192
193    /// Base64 解码错误
194    #[error("base64 decode error: {0}")]
195    Base64Decode(#[from] Base64DecodeError),
196
197    /// HTTP 请求错误
198    #[error("reqwest: {0}")]
199    Reqwest(#[from] ReqwestError),
200
201    /// JSON 序列化/反序列化错误
202    #[error("json error: {0}")]
203    SerdeJson(#[from] SerdeJsonError),
204
205    /// 内部服务器错误
206    #[error("internal error: {0}")]
207    InternalServer(String),
208}
209
210impl From<UnpadError> for Error {
211    fn from(error: UnpadError) -> Self {
212        Error::Unpad(error)
213    }
214}
215
216/// 微信官方错误码枚举
217///
218/// 对应微信小程序 API 返回的错误码，每个错误码都有对应的中文描述。
219///
220///
221/// # 错误码说明
222///
223/// 完整的错误码列表请参考：
224/// [微信官方文档 - 全局返回码说明](https://developers.weixin.qq.com/miniprogram/dev/OpenApiDoc/#%E5%85%A8%E5%B1%80%E8%BF%94%E5%9B%9E%E7%A0%81%E8%AF%B4%E6%98%8E)
225#[derive(Debug, Deserialize_repr, Display)]
226#[repr(i32)]
227pub enum ErrorCode {
228    #[strum(serialize = "系统繁忙，此时请开发者稍候再试")]
229    System = -1,
230    #[strum(
231        serialize = "获取 access_token 时 AppSecret 错误，或者 access_token 无效。请开发者认真比对 AppSecret 的正确性，或查看是否正在为恰当的公众号调用接口"
232    )]
233    InvalidCredential = 40001,
234    #[strum(serialize = "不合法的凭证类型")]
235    InvalidGrantType = 40002,
236    #[strum(serialize = "不合法的 AppID ，请开发者检查 AppID 的正确性，避免异常字符，注意大小写")]
237    InvalidAppId = 40013,
238    #[strum(serialize = "code 无效")]
239    InvalidCode = 40029,
240    #[strum(serialize = "参数错误")]
241    InvalidParameter = 40097,
242    #[strum(serialize = "无效的appsecret，请检查appsecret的正确性")]
243    InvalidSecret = 40125,
244    #[strum(serialize = "将ip添加到ip白名单列表即可")]
245    ForbiddenIp = 40164,
246    #[strum(serialize = "高风险等级用户，小程序登录拦截 。风险等级详见用户安全解方案")]
247    CodeBlocked = 40226,
248    #[strum(serialize = "AppSecret已被冻结，请登录小程序平台解冻后再次调用")]
249    SecretFrozen = 40243,
250    #[strum(serialize = "缺少 access token 参数")]
251    MissingAccessToken = 41001,
252    #[strum(serialize = "缺少 appid 参数")]
253    MissingAppId = 41002,
254    #[strum(serialize = "缺少 secret 参数")]
255    MissingSecret = 41004,
256    MissingCode = 41008,
257    #[strum(serialize = "需要 POST 请求")]
258    RequiredPostMethod = 43002,
259    #[strum(serialize = "调用超过天级别频率限制。可调用clear_quota接口恢复调用额度。")]
260    DailyRequestLimitExceeded = 45009,
261    #[strum(serialize = "API 调用太频繁，请稍候再试")]
262    RateLimitExceeded = 45011,
263    #[strum(serialize = "禁止使用 token 接口")]
264    ForbiddenToken = 50004,
265    #[strum(serialize = "账号已冻结")]
266    AccountFrozen = 50007,
267    #[strum(serialize = "第三方平台 API 需要使用第三方平台专用 token")]
268    ThirdPartyToken = 61024,
269    #[strum(serialize = "session_key is not existed or expired")]
270    SessionKeyNotExistedOrExpired = 87007,
271    #[strum(serialize = "invalid sig_method")]
272    InvalidSignatureMethod = 87008,
273    #[strum(serialize = "无效的签名")]
274    InvalidSignature = 87009,
275    #[strum(serialize = "此次调用需要管理员确认，请耐心等候")]
276    ConfirmRequired = 89503,
277    #[strum(
278        serialize = "该IP调用求请求已被公众号管理员拒绝，请24小时后再试，建议调用前与管理员沟通确认"
279    )]
280    RequestDeniedOneDay = 89506,
281    #[strum(
282        serialize = "该IP调用求请求已被公众号管理员拒绝，请1小时后再试，建议调用前与管理员沟通确认"
283    )]
284    RequestDeniedOneHour = 89507,
285}
286
287impl From<(ErrorCode, String)> for Error {
288    /// 从微信错误码和消息创建 Error
289    ///
290    /// # 参数
291    ///
292    /// - `(code, message)`: 微信错误码和对应的错误消息
293    ///
294    /// # 返回
295    ///
296    /// 对应的 `Error` 枚举变体
297    fn from((code, message): (ErrorCode, String)) -> Self {
298        use ErrorCode::*;
299
300        match code {
301            System => Error::System(message),
302            InvalidCredential => Error::InvalidCredential(message),
303            InvalidGrantType => Error::InvalidGrantType(message),
304            InvalidAppId => Error::InvalidAppId(message),
305            InvalidCode => Error::InvalidCode(message),
306            InvalidParameter => Error::InvalidParameter(message),
307            InvalidSecret => Error::InvalidSecret(message),
308            ForbiddenIp => Error::ForbiddenIp(message),
309            CodeBlocked => Error::CodeBlocked(message),
310            SecretFrozen => Error::SecretFrozen(message),
311            MissingAccessToken => Error::MissingAccessToken(message),
312            MissingAppId => Error::MissingAppId(message),
313            MissingSecret => Error::MissingSecret(message),
314            MissingCode => Error::MissingCode(message),
315            RequiredPostMethod => Error::RequiredPostMethod(message),
316            DailyRequestLimitExceeded => Error::DailyRequestLimitExceeded(message),
317            RateLimitExceeded => Error::RateLimitExceeded(message),
318            ForbiddenToken => Error::ForbiddenToken(message),
319            AccountFrozen => Error::AccountFrozen(message),
320            ThirdPartyToken => Error::ThirdPartyToken(message),
321            SessionKeyNotExistedOrExpired => Error::SessionKeyNotExistedOrExpired(message),
322            InvalidSignatureMethod => Error::InvalidSignatureMethod(message),
323            InvalidSignature => Error::InvalidSignature(message),
324            ConfirmRequired => Error::ConfirmRequired(message),
325            RequestDeniedOneDay => Error::RequestDeniedOneDay(message),
326            RequestDeniedOneHour => Error::RequestDeniedOneHour(message),
327        }
328    }
329}
wechat_minapp/error.rs

wechat_minapp/
error.rs
