nautilus_bitmex/http/
error.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2025 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 BitMEX integration.
17
18use nautilus_network::http::{HttpClientError, StatusCode};
19use serde::{Deserialize, Serialize};
20use thiserror::Error;
21
22/// Build error for query parameter validation.
23#[derive(Debug, Clone, Error)]
24pub enum BitmexBuildError {
25    /// Missing required symbol.
26    #[error("Missing required symbol")]
27    MissingSymbol,
28    /// Invalid count value.
29    #[error("Invalid count: must be between 1 and 500")]
30    InvalidCount,
31    /// Invalid start value.
32    #[error("Invalid start: must be non-negative")]
33    InvalidStart,
34    /// Invalid time range: `start_time` should be less than `end_time`.
35    #[error(
36        "Invalid time range: start_time ({start_time}) must be less than end_time ({end_time})"
37    )]
38    InvalidTimeRange { start_time: i64, end_time: i64 },
39    /// Both orderID and clOrdID specified.
40    #[error("Cannot specify both 'orderID' and 'clOrdID'")]
41    BothOrderIds,
42    /// Missing required order identifier.
43    #[error("Missing required order identifier (orderID or clOrdID)")]
44    MissingOrderId,
45}
46
47/// Represents the JSON structure of an error response returned by the BitMEX API.
48#[derive(Clone, Debug, Deserialize, Serialize)]
49pub struct BitmexErrorResponse {
50    /// The top-level error object included in the BitMEX error response.
51    pub error: BitmexErrorMessage,
52}
53
54/// Contains the specific error details provided by the BitMEX API.
55#[derive(Clone, Debug, Deserialize, Serialize)]
56pub struct BitmexErrorMessage {
57    /// A human-readable explanation of the error condition.
58    pub message: String,
59    /// A short identifier or category for the error, as returned by BitMEX.
60    pub name: String,
61}
62
63/// A typed error enumeration for the BitMEX HTTP client.
64#[derive(Debug, Clone, Error)]
65pub enum BitmexHttpError {
66    /// Error variant when credentials are missing but the request is authenticated.
67    #[error("Missing credentials for authenticated request")]
68    MissingCredentials,
69    /// Errors returned directly by BitMEX.
70    #[error("BitMEX error {error_name}: {message}")]
71    BitmexError { error_name: String, message: String },
72    /// Failure during JSON serialization/deserialization.
73    #[error("JSON error: {0}")]
74    JsonError(String),
75    /// Parameter validation error.
76    #[error("Parameter validation error: {0}")]
77    ValidationError(String),
78    /// Build error for query parameters.
79    #[error("Build error: {0}")]
80    BuildError(#[from] BitmexBuildError),
81    /// Request was canceled, typically due to shutdown or disconnect.
82    #[error("Request canceled: {0}")]
83    Canceled(String),
84    /// Generic network error (for retries, cancellations, etc).
85    #[error("Network error: {0}")]
86    NetworkError(String),
87    /// Any unknown HTTP status or unexpected response from BitMEX.
88    #[error("Unexpected HTTP status code {status}: {body}")]
89    UnexpectedStatus { status: StatusCode, body: String },
90}
91
92impl From<HttpClientError> for BitmexHttpError {
93    fn from(error: HttpClientError) -> Self {
94        Self::NetworkError(error.to_string())
95    }
96}
97
98impl From<String> for BitmexHttpError {
99    fn from(error: String) -> Self {
100        Self::ValidationError(error)
101    }
102}
103
104// Allow use of the `?` operator on `serde_json` results inside the HTTP
105// client implementation by converting them into our typed error.
106impl From<serde_json::Error> for BitmexHttpError {
107    fn from(error: serde_json::Error) -> Self {
108        Self::JsonError(error.to_string())
109    }
110}
111
112impl From<BitmexErrorResponse> for BitmexHttpError {
113    fn from(error: BitmexErrorResponse) -> Self {
114        Self::BitmexError {
115            error_name: error.error.name,
116            message: error.error.message,
117        }
118    }
119}
120
121#[cfg(test)]
122mod tests {
123    use rstest::rstest;
124
125    use super::*;
126    use crate::common::testing::load_test_json;
127
128    #[rstest]
129    fn test_bitmex_build_error_display() {
130        let error = BitmexBuildError::MissingSymbol;
131        assert_eq!(error.to_string(), "Missing required symbol");
132
133        let error = BitmexBuildError::InvalidCount;
134        assert_eq!(
135            error.to_string(),
136            "Invalid count: must be between 1 and 500"
137        );
138
139        let error = BitmexBuildError::InvalidTimeRange {
140            start_time: 100,
141            end_time: 50,
142        };
143        assert_eq!(
144            error.to_string(),
145            "Invalid time range: start_time (100) must be less than end_time (50)"
146        );
147    }
148
149    #[rstest]
150    fn test_bitmex_error_response_from_json() {
151        let json = load_test_json("http_error_response.json");
152
153        let error_response: BitmexErrorResponse = serde_json::from_str(&json).unwrap();
154        assert_eq!(error_response.error.message, "Invalid API Key.");
155        assert_eq!(error_response.error.name, "HTTPError");
156    }
157
158    #[rstest]
159    fn test_bitmex_http_error_from_error_response() {
160        let error_response = BitmexErrorResponse {
161            error: BitmexErrorMessage {
162                message: "Rate limit exceeded".to_string(),
163                name: "RateLimitError".to_string(),
164            },
165        };
166
167        let http_error: BitmexHttpError = error_response.into();
168        assert_eq!(
169            http_error.to_string(),
170            "BitMEX error RateLimitError: Rate limit exceeded"
171        );
172    }
173
174    #[rstest]
175    fn test_bitmex_http_error_from_json_error() {
176        let json_err = serde_json::from_str::<BitmexErrorResponse>("invalid json").unwrap_err();
177        let http_error: BitmexHttpError = json_err.into();
178        assert!(http_error.to_string().contains("JSON error"));
179    }
180
181    #[rstest]
182    fn test_bitmex_http_error_from_string() {
183        let error_msg = "Invalid parameter value".to_string();
184        let http_error: BitmexHttpError = error_msg.into();
185        assert_eq!(
186            http_error.to_string(),
187            "Parameter validation error: Invalid parameter value"
188        );
189    }
190
191    #[rstest]
192    fn test_unexpected_status_error() {
193        let error = BitmexHttpError::UnexpectedStatus {
194            status: StatusCode::BAD_GATEWAY,
195            body: "Server error".to_string(),
196        };
197        assert_eq!(
198            error.to_string(),
199            "Unexpected HTTP status code 502 Bad Gateway: Server error"
200        );
201    }
202}
nautilus_bitmex/http/error.rs

nautilus_bitmex/http/
error.rs
