nautilus_okx/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 OKX integration.
17//!
18//! The JSON error schema is described in the OKX documentation under
19//! *REST API > Error Codes* – <https://www.okx.com/docs-v5/en/#error-codes>.
20//! The types below mirror that structure and are reused across the entire
21//! crate.
22
23use nautilus_network::http::{HttpClientError, StatusCode};
24use serde::Deserialize;
25use thiserror::Error;
26
27/// Represents a build error for query parameter validation.
28#[derive(Debug, Error)]
29pub enum BuildError {
30    /// Missing required instrument ID.
31    #[error("Missing required instrument ID")]
32    MissingInstId,
33    /// Missing required bar interval.
34    #[error("Missing required bar interval")]
35    MissingBar,
36    /// Both after and before cursors specified.
37    #[error("Cannot specify both 'after' and 'before' cursors")]
38    BothCursors,
39    /// Invalid time range: after_ms should be greater than before_ms.
40    #[error(
41        "Invalid time range: after_ms ({after_ms}) must be greater than before_ms ({before_ms})"
42    )]
43    InvalidTimeRange { after_ms: i64, before_ms: i64 },
44    /// Cursor timestamp is in nanoseconds (> 13 digits).
45    #[error("Cursor timestamp appears to be in nanoseconds (> 13 digits)")]
46    CursorIsNanoseconds,
47    /// Limit exceeds maximum allowed value.
48    #[error("Limit exceeds maximum of 300")]
49    LimitTooHigh,
50}
51
52/// Represents the JSON structure of an error response returned by the OKX API.
53#[derive(Clone, Debug, Deserialize)]
54pub struct OKXErrorResponse {
55    /// The top-level error object included in the OKX error response.
56    pub error: OKXErrorMessage,
57}
58
59/// Contains the specific error details provided by the OKX API.
60#[derive(Clone, Debug, Deserialize)]
61pub struct OKXErrorMessage {
62    /// A human-readable explanation of the error condition.
63    pub message: String,
64    /// A short identifier or category for the error, as returned by OKX.
65    pub name: String,
66}
67
68/// A typed error enumeration for the OKX HTTP client.
69#[derive(Debug, Error)]
70pub enum OKXHttpError {
71    /// Error variant when credentials are missing but the request is authenticated.
72    #[error("Missing credentials for authenticated request")]
73    MissingCredentials,
74    /// Errors returned directly by OKX (non-zero code).
75    #[error("OKX error {error_code}: {message}")]
76    OkxError { error_code: String, message: String },
77    /// Failure during JSON serialization/deserialization.
78    #[error("JSON error: {0}")]
79    JsonError(String),
80    /// Parameter validation error.
81    #[error("Parameter validation error: {0}")]
82    ValidationError(String),
83    /// Request was canceled, typically due to shutdown or disconnect.
84    #[error("Request canceled: {0}")]
85    Canceled(String),
86    /// Wrapping the underlying HttpClientError from the network crate.
87    #[error("Network error: {0}")]
88    HttpClientError(#[from] HttpClientError),
89    /// Any unknown HTTP status or unexpected response from OKX.
90    #[error("Unexpected HTTP status code {status}: {body}")]
91    UnexpectedStatus { status: StatusCode, body: String },
92}
93
94impl From<String> for OKXHttpError {
95    fn from(error: String) -> Self {
96        Self::ValidationError(error)
97    }
98}
99
100// Allow use of the `?` operator on `serde_json` results inside the HTTP
101// client implementation by converting them into our typed error.
102impl From<serde_json::Error> for OKXHttpError {
103    fn from(error: serde_json::Error) -> Self {
104        Self::JsonError(error.to_string())
105    }
106}
nautilus_okx/http/error.rs

nautilus_okx/http/
error.rs
