nautilus_lighter/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//! HTTP error taxonomy for Lighter REST responses.
17
18use nautilus_network::http::HttpClientError;
19use thiserror::Error;
20
21/// Result alias for Lighter HTTP operations.
22pub type LighterHttpResult<T> = Result<T, LighterHttpError>;
23
24/// Errors emitted by the Lighter HTTP client.
25#[derive(Debug, Clone, Error)]
26pub enum LighterHttpError {
27    /// Network-level failure (transport, DNS, TLS).
28    #[error("network error: {0}")]
29    Network(String),
30    /// HTTP-level failure with status code and body.
31    #[error("HTTP {status}: {body}")]
32    Http { status: u16, body: String },
33    /// Rate limit exceeded.
34    #[error("rate limit exceeded: {0}")]
35    RateLimit(String),
36    /// Venue returned a structured error code.
37    #[error("venue error {code}: {message}")]
38    Venue { code: i64, message: String },
39    /// Failed to parse a venue response.
40    #[error("parse error: {0}")]
41    Parse(String),
42}
43
44impl From<HttpClientError> for LighterHttpError {
45    fn from(error: HttpClientError) -> Self {
46        Self::Network(error.to_string())
47    }
48}
49
50impl From<serde_json::Error> for LighterHttpError {
51    fn from(error: serde_json::Error) -> Self {
52        Self::Parse(error.to_string())
53    }
54}
55
56impl From<anyhow::Error> for LighterHttpError {
57    fn from(error: anyhow::Error) -> Self {
58        Self::Parse(error.to_string())
59    }
60}
61
62/// Returns `true` if a request producing this error should be retried.
63///
64/// Retryable shapes are transport-layer failures, server-side 5xx, and rate limits.
65/// Venue-semantic errors (4xx other than 429, `Venue`, `Parse`) are surfaced unchanged.
66#[must_use]
67pub fn should_retry_lighter_http_error(error: &LighterHttpError) -> bool {
68    match error {
69        LighterHttpError::Network(_) | LighterHttpError::RateLimit(_) => true,
70        LighterHttpError::Http { status, .. } => *status >= 500,
71        LighterHttpError::Venue { .. } | LighterHttpError::Parse(_) => false,
72    }
73}
74
75/// Constructs a transport-shaped error for retry-manager timeout / cancellation paths.
76#[must_use]
77pub fn create_lighter_http_timeout_error(msg: String) -> LighterHttpError {
78    LighterHttpError::Network(msg)
79}
80
81#[cfg(test)]
82mod tests {
83    use rstest::rstest;
84
85    use super::*;
86
87    #[rstest]
88    #[case::network_retries(LighterHttpError::Network("dns failure".into()), true)]
89    #[case::rate_limit_retries(LighterHttpError::RateLimit("429".into()), true)]
90    #[case::server_5xx_retries(LighterHttpError::Http { status: 503, body: "busy".into() }, true)]
91    #[case::server_500_retries(LighterHttpError::Http { status: 500, body: "boom".into() }, true)]
92    #[case::client_400_does_not_retry(LighterHttpError::Http { status: 400, body: "bad".into() }, false)]
93    #[case::client_404_does_not_retry(LighterHttpError::Http { status: 404, body: "missing".into() }, false)]
94    #[case::venue_does_not_retry(LighterHttpError::Venue { code: 20001, message: "invalid".into() }, false)]
95    #[case::parse_does_not_retry(LighterHttpError::Parse("bad json".into()), false)]
96    fn test_should_retry_lighter_http_error(
97        #[case] error: LighterHttpError,
98        #[case] expected: bool,
99    ) {
100        assert_eq!(should_retry_lighter_http_error(&error), expected);
101    }
102}
nautilus_lighter/http/error.rs

nautilus_lighter/http/
error.rs
