Skip to main content

financial_api/
error.rs

1/// 请求领域值或客户端配置值无效。
2#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
3#[error("invalid {field}: {problem}")]
4pub struct ValidationError {
5    field: &'static str,
6    problem: &'static str,
7}
8
9impl ValidationError {
10    pub(crate) const fn new(field: &'static str, problem: &'static str) -> Self {
11        Self { field, problem }
12    }
13
14    /// 无效字段。
15    #[must_use]
16    pub const fn field(&self) -> &'static str {
17        self.field
18    }
19
20    /// 对违反约束的稳定描述。
21    #[must_use]
22    pub const fn problem(&self) -> &'static str {
23        self.problem
24    }
25}
26
27/// 上游非零业务结果对应的稳定恢复类别。
28#[derive(Debug, Clone, Copy, PartialEq, Eq)]
29#[non_exhaustive]
30pub enum BusinessErrorKind {
31    InvalidRequest,
32    Authentication,
33    PermissionDenied,
34    TargetNotFound,
35    DataNotReady,
36    UnsupportedTarget,
37    RateLimited,
38    UpstreamUnavailable,
39    Other,
40}
41
42/// 从响应信封中解码出的非零业务结果。
43#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
44#[error("upstream business request failed with code {code}")]
45pub struct BusinessError {
46    code: i64,
47    message: String,
48    request_id: String,
49}
50
51impl BusinessError {
52    pub(crate) fn new(code: i64, message: String, request_id: String) -> Self {
53        Self {
54            code,
55            message,
56            request_id,
57        }
58    }
59
60    /// 服务返回的数字业务结果码。
61    #[must_use]
62    pub const fn code(&self) -> i64 {
63        self.code
64    }
65
66    /// 上游结果描述。
67    #[must_use]
68    pub fn message(&self) -> &str {
69        &self.message
70    }
71
72    /// 上游请求追踪标识。
73    #[must_use]
74    pub fn request_id(&self) -> &str {
75        &self.request_id
76    }
77
78    /// 面向恢复动作的 [`Self::code`] 分类。
79    #[must_use]
80    pub const fn kind(&self) -> BusinessErrorKind {
81        match self.code {
82            1001..=1004 => BusinessErrorKind::InvalidRequest,
83            2001 | 2002 | 2004 => BusinessErrorKind::Authentication,
84            2003 => BusinessErrorKind::PermissionDenied,
85            3001 => BusinessErrorKind::TargetNotFound,
86            3002 | 4040 => BusinessErrorKind::DataNotReady,
87            3004 => BusinessErrorKind::UnsupportedTarget,
88            4001 => BusinessErrorKind::RateLimited,
89            5001..=5003 => BusinessErrorKind::UpstreamUnavailable,
90            _ => BusinessErrorKind::Other,
91        }
92    }
93}
94
95/// 配置或调用 API 时产生的失败。
96#[derive(Debug, thiserror::Error)]
97#[non_exhaustive]
98pub enum Error {
99    #[error(transparent)]
100    InvalidInput(#[from] ValidationError),
101
102    #[error("invalid client configuration")]
103    InvalidConfiguration {
104        #[source]
105        source: reqwest::Error,
106    },
107
108    #[error("HTTP transport failed")]
109    Transport {
110        #[source]
111        source: reqwest::Error,
112    },
113
114    #[error("unexpected HTTP status {status}")]
115    HttpStatus { status: u16 },
116
117    #[error("response did not match the API envelope")]
118    InvalidResponse {
119        #[source]
120        source: serde_json::Error,
121    },
122
123    #[error(transparent)]
124    Business(#[from] BusinessError),
125
126    #[error("environment variable HITHINK_FINANCE_API_KEY is not configured")]
127    MissingApiKey,
128}