nautilus_architect_ax/http/
error.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Error structures and enumerations for the AX Exchange HTTP integration.
17
18use nautilus_network::http::HttpClientError;
19use serde::{Deserialize, Serialize};
20use thiserror::Error;
21
22/// Build error for query parameter validation.
23#[derive(Debug, Clone, Error)]
24pub enum AxBuildError {
25    /// Missing required symbol.
26    #[error("Missing required symbol")]
27    MissingSymbol,
28    /// Invalid limit value.
29    #[error("Invalid limit: {0}")]
30    InvalidLimit(String),
31    /// Invalid time range: `start` should be less than `end`.
32    #[error("Invalid time range: start ({start}) must be less than end ({end})")]
33    InvalidTimeRange { start: i64, end: i64 },
34    /// Missing required order identifier.
35    #[error("Missing required order identifier")]
36    MissingOrderId,
37}
38
39/// Represents the JSON structure of an error response returned by the AX Exchange API.
40///
41/// Note: The exact error response format will be updated as we learn more about
42/// the AX Exchange API error structure.
43#[derive(Clone, Debug, Deserialize, Serialize)]
44pub struct AxErrorResponse {
45    /// Error code or type.
46    #[serde(default)]
47    pub error: Option<String>,
48    /// A human-readable explanation of the error condition.
49    #[serde(default)]
50    pub message: Option<String>,
51    /// HTTP status code.
52    #[serde(default)]
53    pub status: Option<u16>,
54}
55
56/// A typed error enumeration for the Ax HTTP client.
57#[derive(Debug, Clone, Error)]
58pub enum AxHttpError {
59    /// Error variant when credentials are missing but the request is authenticated.
60    #[error("Missing credentials for authenticated request")]
61    MissingCredentials,
62    /// Error variant when session token is not set (not yet authenticated).
63    #[error("Session token not set (not authenticated)")]
64    MissingSessionToken,
65    /// Errors returned directly by AX Exchange API.
66    #[error("AX Exchange API error: {message}")]
67    ApiError { message: String },
68    /// Failure during JSON serialization/deserialization.
69    #[error("JSON error: {0}")]
70    JsonError(String),
71    /// Parameter validation error.
72    #[error("Parameter validation error: {0}")]
73    ValidationError(String),
74    /// Build error for query parameters.
75    #[error("Build error: {0}")]
76    BuildError(#[from] AxBuildError),
77    /// Request was canceled, typically due to shutdown or disconnect.
78    #[error("Request canceled: {0}")]
79    Canceled(String),
80    /// Generic network error (for retries, cancellations, etc).
81    #[error("Network error: {0}")]
82    NetworkError(String),
83    /// Any unknown HTTP status or unexpected response from Ax.
84    #[error("Unexpected HTTP status code {status}: {body}")]
85    UnexpectedStatus { status: u16, body: String },
86}
87
88impl From<HttpClientError> for AxHttpError {
89    fn from(error: HttpClientError) -> Self {
90        Self::NetworkError(error.to_string())
91    }
92}
93
94impl From<String> for AxHttpError {
95    fn from(error: String) -> Self {
96        Self::ValidationError(error)
97    }
98}
99
100impl From<serde_json::Error> for AxHttpError {
101    fn from(error: serde_json::Error) -> Self {
102        Self::JsonError(error.to_string())
103    }
104}
105
106impl From<AxErrorResponse> for AxHttpError {
107    fn from(error: AxErrorResponse) -> Self {
108        let message = error
109            .message
110            .or(error.error)
111            .unwrap_or_else(|| "Unknown error".to_string());
112        Self::ApiError { message }
113    }
114}
115
116impl AxHttpError {
117    /// Returns `true` if the error is transient and the request should be retried.
118    ///
119    /// Retries on network errors, rate limiting (429), and server errors (5xx).
120    #[must_use]
121    pub fn is_retryable(&self) -> bool {
122        crate::common::retry::should_retry_http(self)
123    }
124}
125
126#[cfg(test)]
127mod tests {
128    use rstest::rstest;
129
130    use super::*;
131
132    #[rstest]
133    fn test_architect_build_error_display() {
134        let error = AxBuildError::MissingSymbol;
135        assert_eq!(error.to_string(), "Missing required symbol");
136
137        let error = AxBuildError::InvalidLimit("must be positive".to_string());
138        assert_eq!(error.to_string(), "Invalid limit: must be positive");
139
140        let error = AxBuildError::InvalidTimeRange {
141            start: 100,
142            end: 50,
143        };
144        assert_eq!(
145            error.to_string(),
146            "Invalid time range: start (100) must be less than end (50)"
147        );
148    }
149
150    #[rstest]
151    fn test_architect_http_error_from_json_error() {
152        let json_err = serde_json::from_str::<serde_json::Value>("invalid json")
153            .expect_err("Should fail to parse");
154        let http_err = AxHttpError::from(json_err);
155
156        assert!(matches!(http_err, AxHttpError::JsonError(_)));
157    }
158
159    #[rstest]
160    fn test_architect_http_error_from_string() {
161        let error = AxHttpError::from("Test validation error".to_string());
162        assert_eq!(
163            error.to_string(),
164            "Parameter validation error: Test validation error"
165        );
166    }
167
168    #[rstest]
169    fn test_architect_error_response_to_http_error() {
170        let error_response = AxErrorResponse {
171            error: Some("INVALID_REQUEST".to_string()),
172            message: Some("Invalid parameter".to_string()),
173            status: Some(400),
174        };
175
176        let http_error = AxHttpError::from(error_response);
177        assert_eq!(
178            http_error.to_string(),
179            "AX Exchange API error: Invalid parameter"
180        );
181    }
182
183    #[rstest]
184    #[case(AxHttpError::NetworkError("boom".to_string()), true)]
185    #[case(AxHttpError::UnexpectedStatus { status: 500, body: String::new() }, true)]
186    #[case(AxHttpError::UnexpectedStatus { status: 502, body: String::new() }, true)]
187    #[case(AxHttpError::UnexpectedStatus { status: 503, body: String::new() }, true)]
188    #[case(AxHttpError::UnexpectedStatus { status: 599, body: String::new() }, true)]
189    #[case(AxHttpError::UnexpectedStatus { status: 600, body: String::new() }, true)]
190    #[case(AxHttpError::UnexpectedStatus { status: 429, body: String::new() }, true)]
191    #[case(AxHttpError::UnexpectedStatus { status: 408, body: String::new() }, false)]
192    #[case(AxHttpError::UnexpectedStatus { status: 425, body: String::new() }, false)]
193    #[case(AxHttpError::UnexpectedStatus { status: 400, body: String::new() }, false)]
194    #[case(AxHttpError::UnexpectedStatus { status: 401, body: String::new() }, false)]
195    #[case(AxHttpError::UnexpectedStatus { status: 404, body: String::new() }, false)]
196    #[case(AxHttpError::MissingCredentials, false)]
197    #[case(AxHttpError::MissingSessionToken, false)]
198    #[case(AxHttpError::ApiError { message: "bad".to_string() }, false)]
199    #[case(AxHttpError::JsonError("bad".to_string()), false)]
200    #[case(AxHttpError::ValidationError("bad".to_string()), false)]
201    #[case(AxHttpError::BuildError(AxBuildError::MissingSymbol), false)]
202    #[case(AxHttpError::Canceled("shutdown".to_string()), false)]
203    fn test_is_retryable(#[case] error: AxHttpError, #[case] expected: bool) {
204        assert_eq!(error.is_retryable(), expected);
205    }
206}
nautilus_architect_ax/http/error.rs

nautilus_architect_ax/http/
error.rs
