Skip to main content

financial_api/
error.rs

1/// A request-domain or client configuration value was invalid.
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    /// The invalid field.
15    #[must_use]
16    pub const fn field(&self) -> &'static str {
17        self.field
18    }
19
20    /// A stable description of the violated constraint.
21    #[must_use]
22    pub const fn problem(&self) -> &'static str {
23        self.problem
24    }
25}
26
27/// Stable recovery category for an upstream non-zero business result.
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/// A decoded non-zero business result from the response envelope.
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    /// Numeric business result code returned by the service.
61    #[must_use]
62    pub const fn code(&self) -> i64 {
63        self.code
64    }
65
66    /// Upstream result description.
67    #[must_use]
68    pub fn message(&self) -> &str {
69        &self.message
70    }
71
72    /// Upstream request trace identifier.
73    #[must_use]
74    pub fn request_id(&self) -> &str {
75        &self.request_id
76    }
77
78    /// Recovery-oriented classification of [`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/// Failures produced while configuring or calling the 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: Option<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}