aimux_core/
error.rs

1//! Error types for aimux-core.
2
3use serde::{Deserialize, Serialize};
4use thiserror::Error;
5use ts_rs::TS;
6
7/// Unified error type for all aimux operations.
8#[derive(Debug, Clone, Serialize, Deserialize, TS, Error)]
9#[ts(export)]
10pub enum AiMuxError {
11    #[error("provider error: {0}")]
12    Provider(String),
13
14    #[error("HTTP error: {0}")]
15    Http(String),
16
17    #[error("JSON error: {0}")]
18    Json(String),
19
20    #[error("stream error: {0}")]
21    Stream(String),
22
23    #[error("tool error: {0}")]
24    Tool(String),
25
26    #[error("invalid argument: {0}")]
27    InvalidArgument(String),
28
29    #[error("invalid prompt: {0}")]
30    InvalidPrompt(String),
31
32    #[error("rate limited: retry after {retry_after_ms}ms")]
33    RateLimited { retry_after_ms: u64 },
34
35    #[error("authentication failed: {0}")]
36    Auth(String),
37
38    #[error("model not found: {0}")]
39    ModelNotFound(String),
40
41    #[error("unsupported functionality: {0}")]
42    Unsupported(String),
43
44    #[error("no such model: {0}")]
45    NoSuchModel(String),
46
47    #[error("unknown provider: {0}")]
48    UnknownProvider(String),
49
50    #[error("API call error: {0}")]
51    ApiCall(String),
52
53    #[error("request timed out: {0}")]
54    Timeout(String),
55
56    #[error("request aborted")]
57    Aborted,
58
59    #[error("{0}")]
60    Other(String),
61}
62
63impl From<serde_json::Error> for AiMuxError {
64    fn from(e: serde_json::Error) -> Self {
65        AiMuxError::Json(e.to_string())
66    }
67}
68
69impl AiMuxError {
70    /// Returns `true` if the error is transient and can be retried.
71    pub fn is_retryable(&self) -> bool {
72        matches!(
73            self,
74            AiMuxError::RateLimited { .. } | AiMuxError::Http(_) | AiMuxError::ApiCall(_)
75        )
76    }
77
78    /// Returns the retry-after delay hint (in milliseconds) carried by this
79    /// error, if any. Currently only `RateLimited` carries a hint (from a
80    /// `retry-after-ms` / `retry-after` response header). Returns `None` for
81    /// errors that don't advertise a delay, in which case the retry strategy
82    /// falls back to exponential backoff.
83    ///
84    /// Mirrors the header-consulting behaviour of
85    /// `retryWithExponentialBackoffRespectingRetryHeaders` in the TS SDK.
86    pub fn retry_after_hint(&self) -> Option<i64> {
87        match self {
88            AiMuxError::RateLimited { retry_after_ms } => Some(*retry_after_ms as i64),
89            _ => None,
90        }
91    }
92
93    /// Returns the error variant name as a string (e.g. `"Auth"`, `"Provider"`,
94    /// `"RateLimited"`). Used by FFI bindings to give callers a machine-readable
95    /// error type alongside the human-readable message.
96    pub fn error_type(&self) -> &'static str {
97        match self {
98            AiMuxError::Provider(_) => "Provider",
99            AiMuxError::Http(_) => "Http",
100            AiMuxError::Json(_) => "Json",
101            AiMuxError::Stream(_) => "Stream",
102            AiMuxError::Tool(_) => "Tool",
103            AiMuxError::InvalidArgument(_) => "InvalidArgument",
104            AiMuxError::InvalidPrompt(_) => "InvalidPrompt",
105            AiMuxError::RateLimited { .. } => "RateLimited",
106            AiMuxError::Auth(_) => "Auth",
107            AiMuxError::ModelNotFound(_) => "ModelNotFound",
108            AiMuxError::Unsupported(_) => "Unsupported",
109            AiMuxError::NoSuchModel(_) => "NoSuchModel",
110            AiMuxError::UnknownProvider(_) => "UnknownProvider",
111            AiMuxError::ApiCall(_) => "ApiCall",
112            AiMuxError::Timeout(_) => "Timeout",
113            AiMuxError::Aborted => "Aborted",
114            AiMuxError::Other(_) => "Other",
115        }
116    }
117
118    /// Returns the HTTP status code carried by this error, if any.
119    ///
120    /// HTTP-layer errors created by `parse_provider_error` and
121    /// `send_with_retry_raw` embed the status code in the message as
122    /// `"HTTP {status}: ..."`. This method extracts it. Errors that don't
123    /// originate from an HTTP response return `None`.
124    pub fn status_code(&self) -> Option<u16> {
125        let message = match self {
126            AiMuxError::Provider(m)
127            | AiMuxError::Http(m)
128            | AiMuxError::Auth(m)
129            | AiMuxError::ApiCall(m)
130            | AiMuxError::ModelNotFound(m) => m,
131            _ => return None,
132        };
133        // Parse "HTTP 403: ..." → 403
134        let rest = message.strip_prefix("HTTP ")?;
135        let code_str: String = rest.chars().take_while(|c| c.is_ascii_digit()).collect();
136        code_str.parse().ok()
137    }
138}
aimux_core/error.rs

aimux_core/
error.rs
