llm/
error.rs

1use std::fmt;
2
3use thiserror::Error;
4
5#[doc = include_str!("docs/llm_error.md")]
6#[derive(Debug, Error, Clone)]
7pub enum LlmError {
8    /// Environment variable not set or invalid
9    #[error("{0} environment variable not set")]
10    MissingApiKey(String),
11    /// HTTP client creation failed
12    #[error("Failed to create HTTP client: {0}")]
13    HttpClientCreation(String),
14    /// Normalized provider-side failure carrying retry classification and
15    /// support diagnostics (HTTP status, request ID, provider error code).
16    #[error("{0}")]
17    Provider(#[from] ProviderError),
18    /// IO error while reading stream
19    #[error("IO error reading stream: {0}")]
20    IoError(String),
21    /// JSON parsing/serialization error
22    #[error("JSON parsing error: {0}")]
23    JsonParsing(String),
24    /// Tool parameter parsing error
25    #[error("Failed to parse tool parameters for {tool_name}: {error}")]
26    ToolParameterParsing { tool_name: String, error: String },
27    /// OAuth authentication error
28    #[error("OAuth error: {0}")]
29    OAuthError(String),
30    /// The message contained only content types this provider doesn't support
31    #[error("Unsupported content: {0}")]
32    UnsupportedContent(String),
33    /// Provider endpoint URL has not been configured.
34    #[error("Provider '{provider}' requires a URL configured via providers.{provider}.url")]
35    MissingProviderUrl { provider: String },
36    /// Provider name is not registered with the model parser.
37    #[error("Unknown provider: {provider}")]
38    UnknownProvider { provider: String },
39    /// The model spec did not yield any usable provider.
40    #[error("No models provided")]
41    EmptyModelSpec,
42    /// A single-model-only config field was reused across multiple models of the
43    /// same provider within one alloy spec (e.g. bedrock `inferenceProfileArn`
44    /// or openai-compatible `requestModel`).
45    #[error("providers.{provider}.{field} cannot be used with multiple {provider} models in one alloy spec")]
46    DuplicateProvider { provider: String, field: String },
47    /// A `provider:model` identity could not be parsed.
48    #[error("Invalid model spec: {0}")]
49    InvalidModelSpec(String),
50    /// A provider request body could not be constructed (e.g. an SDK builder
51    /// rejected the input or contained malformed data).
52    #[error("Failed to build provider request: {0}")]
53    ProviderRequest(String),
54    /// An upstream client library rejected an argument as invalid.
55    #[error("Invalid argument: {0}")]
56    InvalidArgument(String),
57}
58
59#[derive(Debug, Clone, Copy, PartialEq, Eq)]
60pub enum ProviderErrorKind {
61    Authentication,
62    Api,
63    RateLimit,
64    Server,
65    Timeout,
66    Network,
67    StreamInterrupted,
68    Unknown,
69}
70
71impl ProviderErrorKind {
72    pub fn is_retryable(&self) -> bool {
73        matches!(
74            self,
75            Self::RateLimit | Self::Server | Self::Timeout | Self::Network | Self::StreamInterrupted | Self::Unknown
76        )
77    }
78}
79
80#[derive(Debug, Clone, PartialEq, Eq)]
81pub struct ProviderError {
82    pub kind: ProviderErrorKind,
83    pub message: String,
84    pub http_status: Option<u16>,
85    pub request_id: Option<String>,
86    pub code: Option<String>,
87}
88
89impl ProviderError {
90    pub fn new(kind: ProviderErrorKind, message: impl Into<String>) -> Self {
91        Self { kind, message: message.into(), http_status: None, request_id: None, code: None }
92    }
93
94    pub fn authentication(message: impl Into<String>) -> Self {
95        Self::new(ProviderErrorKind::Authentication, message)
96    }
97
98    pub fn api(message: impl Into<String>) -> Self {
99        Self::new(ProviderErrorKind::Api, message)
100    }
101
102    pub fn rate_limit(message: impl Into<String>) -> Self {
103        Self::new(ProviderErrorKind::RateLimit, message)
104    }
105
106    pub fn server(message: impl Into<String>) -> Self {
107        Self::new(ProviderErrorKind::Server, message)
108    }
109
110    pub fn timeout(message: impl Into<String>) -> Self {
111        Self::new(ProviderErrorKind::Timeout, message)
112    }
113
114    pub fn network(message: impl Into<String>) -> Self {
115        Self::new(ProviderErrorKind::Network, message)
116    }
117
118    pub fn stream_interrupted(message: impl Into<String>) -> Self {
119        Self::new(ProviderErrorKind::StreamInterrupted, message)
120    }
121
122    pub fn from_http_status(status: u16, message: impl Into<String>) -> Self {
123        match status {
124            401 | 403 => Self::authentication(message),
125            408 | 504 => Self::timeout(message),
126            429 => Self::rate_limit(message),
127            s if (500..600).contains(&s) => Self::server(message),
128            _ => Self::api(message),
129        }
130        .with_http_status(status)
131    }
132
133    pub fn with_http_status(mut self, status: u16) -> Self {
134        self.http_status = Some(status);
135        self
136    }
137
138    pub fn with_http_metadata(mut self, status: Option<u16>, request_id: Option<String>) -> Self {
139        self.http_status = status;
140        self.request_id = request_id;
141        self
142    }
143
144    pub fn with_code(mut self, code: Option<String>) -> Self {
145        self.code = code;
146        self
147    }
148
149    pub fn with_request_id(mut self, request_id: Option<String>) -> Self {
150        self.request_id = request_id;
151        self
152    }
153
154    pub fn is_retryable(&self) -> bool {
155        self.kind.is_retryable()
156    }
157}
158
159impl fmt::Display for ProviderError {
160    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
161        let prefix = match self.kind {
162            ProviderErrorKind::Authentication => "Authentication error",
163            ProviderErrorKind::Api => "API error",
164            ProviderErrorKind::RateLimit => "Rate limited",
165            ProviderErrorKind::Server => "Server error",
166            ProviderErrorKind::Timeout => "Request timed out",
167            ProviderErrorKind::Network => "Network error",
168            ProviderErrorKind::StreamInterrupted => "Stream interrupted",
169            ProviderErrorKind::Unknown => "Provider error",
170        };
171        write!(f, "{prefix}: {}", self.message)?;
172        let mut diagnostics = Vec::new();
173        if let Some(status) = self.http_status {
174            diagnostics.push(format!("status {status}"));
175        }
176        if let Some(code) = &self.code {
177            diagnostics.push(format!("code {code}"));
178        }
179        if let Some(request_id) = &self.request_id {
180            diagnostics.push(format!("request_id {request_id}"));
181        }
182        if !diagnostics.is_empty() {
183            write!(f, " ({})", diagnostics.join(", "))?;
184        }
185        Ok(())
186    }
187}
188
189impl std::error::Error for ProviderError {}
190
191impl LlmError {
192    pub fn is_retryable(&self) -> bool {
193        self.provider().is_some_and(ProviderError::is_retryable)
194    }
195
196    pub fn provider(&self) -> Option<&ProviderError> {
197        match self {
198            Self::Provider(error) => Some(error),
199            _ => None,
200        }
201    }
202}
203
204impl From<reqwest::Error> for LlmError {
205    fn from(error: reqwest::Error) -> Self {
206        if error.is_timeout() {
207            return ProviderError::timeout(error.to_string()).into();
208        }
209        if error.is_connect() || error.is_request() {
210            return ProviderError::network(error.to_string()).into();
211        }
212        match error.status().map(|s| s.as_u16()) {
213            Some(status) => ProviderError::from_http_status(status, error.to_string()).into(),
214            None => ProviderError::network(error.to_string()).into(),
215        }
216    }
217}
218
219impl From<serde_json::Error> for LlmError {
220    fn from(error: serde_json::Error) -> Self {
221        LlmError::JsonParsing(error.to_string())
222    }
223}
224
225impl From<std::io::Error> for LlmError {
226    fn from(error: std::io::Error) -> Self {
227        LlmError::IoError(error.to_string())
228    }
229}
230
231impl From<reqwest::header::InvalidHeaderValue> for LlmError {
232    fn from(error: reqwest::header::InvalidHeaderValue) -> Self {
233        LlmError::ProviderRequest(error.to_string())
234    }
235}
236
237impl From<async_openai::error::OpenAIError> for LlmError {
238    fn from(error: async_openai::error::OpenAIError) -> Self {
239        use async_openai::error::OpenAIError;
240        match error {
241            OpenAIError::Reqwest(e) => LlmError::from(e),
242            OpenAIError::StreamError(e) => ProviderError::stream_interrupted(e.to_string()).into(),
243            OpenAIError::ApiError(api_err) => {
244                let status = api_err.status_code.as_u16();
245                let code = api_err.api_error.code.clone();
246                let message = format!("{status} {}", api_err.api_error);
247                ProviderError::from_http_status(status, message).with_code(code).into()
248            }
249            OpenAIError::JSONDeserialize(e, _) => LlmError::JsonParsing(e.to_string()),
250            OpenAIError::Boxed(e) => e
251                .downcast::<ProviderError>()
252                .map_or_else(|error| ProviderError::api(error.to_string()).into(), |error| (*error).into()),
253            OpenAIError::FileSaveError(s) | OpenAIError::FileReadError(s) => LlmError::IoError(s),
254            OpenAIError::InvalidArgument(s) => LlmError::InvalidArgument(s),
255        }
256    }
257}
258
259#[cfg(feature = "codex")]
260impl From<aether_auth::OAuthError> for LlmError {
261    fn from(error: aether_auth::OAuthError) -> Self {
262        LlmError::OAuthError(error.to_string())
263    }
264}
265
266pub type Result<T> = std::result::Result<T, LlmError>;
267
268#[cfg(test)]
269mod tests {
270    use super::*;
271
272    #[test]
273    fn retryable_kinds_cover_transient_failures() {
274        assert!(!ProviderErrorKind::Authentication.is_retryable());
275        assert!(!ProviderErrorKind::Api.is_retryable());
276        assert!(ProviderErrorKind::RateLimit.is_retryable());
277        assert!(ProviderErrorKind::Server.is_retryable());
278        assert!(ProviderErrorKind::Timeout.is_retryable());
279        assert!(ProviderErrorKind::Network.is_retryable());
280        assert!(ProviderErrorKind::StreamInterrupted.is_retryable());
281        assert!(ProviderErrorKind::Unknown.is_retryable());
282    }
283
284    #[test]
285    fn http_status_classification_covers_known_statuses() {
286        assert_eq!(ProviderError::from_http_status(401, "d").kind, ProviderErrorKind::Authentication);
287        assert_eq!(ProviderError::from_http_status(403, "d").kind, ProviderErrorKind::Authentication);
288        assert_eq!(ProviderError::from_http_status(408, "d").kind, ProviderErrorKind::Timeout);
289        assert!(ProviderError::from_http_status(408, "d").is_retryable());
290        assert_eq!(ProviderError::from_http_status(429, "d").kind, ProviderErrorKind::RateLimit);
291        assert_eq!(ProviderError::from_http_status(500, "d").kind, ProviderErrorKind::Server);
292        assert_eq!(ProviderError::from_http_status(503, "d").kind, ProviderErrorKind::Server);
293        assert_eq!(ProviderError::from_http_status(400, "d").kind, ProviderErrorKind::Api);
294        assert!(!ProviderError::from_http_status(400, "d").is_retryable());
295        assert_eq!(ProviderError::from_http_status(404, "d").kind, ProviderErrorKind::Api);
296    }
297
298    #[test]
299    fn display_includes_diagnostics_when_present() {
300        let error = ProviderError::server("boom").with_http_status(200).with_code(Some("server_error".into()));
301        let text = error.to_string();
302        assert!(text.contains("boom"));
303        assert!(text.contains("status 200"));
304        assert!(text.contains("code server_error"));
305        let error = error.with_request_id(Some("req-1".into()));
306        assert!(error.to_string().contains("request_id req-1"));
307    }
308
309    #[test]
310    fn display_omits_suffix_when_no_metadata() {
311        let error = ProviderError::api("bad");
312        assert_eq!(error.to_string(), "API error: bad");
313    }
314
315    #[test]
316    fn is_retryable() {
317        assert!(LlmError::from(ProviderError::rate_limit("rl")).is_retryable());
318        assert!(LlmError::from(ProviderError::server("x").with_http_status(503)).is_retryable());
319        assert!(LlmError::from(ProviderError::server("stream-level")).is_retryable());
320        assert!(LlmError::from(ProviderError::timeout("t")).is_retryable());
321        assert!(LlmError::from(ProviderError::network("n")).is_retryable());
322        assert!(LlmError::from(ProviderError::stream_interrupted("s")).is_retryable());
323
324        assert!(!LlmError::from(ProviderError::api("x")).is_retryable());
325        assert!(!LlmError::from(ProviderError::authentication("x")).is_retryable());
326        assert!(!LlmError::MissingApiKey("x".into()).is_retryable());
327        assert!(!LlmError::HttpClientCreation("x".into()).is_retryable());
328        assert!(!LlmError::IoError("x".into()).is_retryable());
329        assert!(!LlmError::JsonParsing("x".into()).is_retryable());
330        assert!(!LlmError::ToolParameterParsing { tool_name: "t".into(), error: "e".into() }.is_retryable());
331        assert!(!LlmError::OAuthError("x".into()).is_retryable());
332        assert!(!LlmError::UnsupportedContent("x".into()).is_retryable());
333        assert!(!LlmError::MissingProviderUrl { provider: "azure-foundry".into() }.is_retryable());
334        assert!(!LlmError::UnknownProvider { provider: "foo".into() }.is_retryable());
335        assert!(!LlmError::EmptyModelSpec.is_retryable());
336        assert!(
337            !LlmError::DuplicateProvider { provider: "bedrock".into(), field: "inferenceProfileArn".into() }
338                .is_retryable()
339        );
340        assert!(!LlmError::InvalidModelSpec("x".into()).is_retryable());
341        assert!(!LlmError::ProviderRequest("x".into()).is_retryable());
342        assert!(!LlmError::InvalidArgument("x".into()).is_retryable());
343    }
344
345    #[test]
346    fn async_openai_api_error_preserves_status_and_code() {
347        use async_openai::error::{ApiError, ApiErrorResponse};
348        let response = ApiErrorResponse {
349            status_code: reqwest::StatusCode::SERVICE_UNAVAILABLE,
350            api_error: ApiError {
351                message: "overloaded".to_string(),
352                r#type: None,
353                param: None,
354                code: Some("server_error".to_string()),
355            },
356        };
357        let error = LlmError::from(async_openai::error::OpenAIError::ApiError(response));
358        let provider = error.provider().expect("expected provider error");
359        assert_eq!(provider.kind, ProviderErrorKind::Server);
360        assert_eq!(provider.http_status, Some(503));
361        assert_eq!(provider.code.as_deref(), Some("server_error"));
362        assert!(error.is_retryable());
363    }
364
365    #[test]
366    fn async_openai_boxed_provider_error_preserves_classification_and_diagnostics() {
367        let provider = ProviderError::rate_limit("slow down")
368            .with_http_status(429)
369            .with_code(Some("429".into()))
370            .with_request_id(Some("request-123".into()));
371        let error = LlmError::from(async_openai::error::OpenAIError::Boxed(Box::new(provider.clone())));
372
373        assert_eq!(error.provider(), Some(&provider));
374        assert!(error.is_retryable());
375    }
376
377    #[test]
378    fn async_openai_stream_error_is_interruption() {
379        let io = std::io::Error::other("eof");
380        let error = LlmError::from(async_openai::error::OpenAIError::StreamError(Box::new(
381            async_openai::error::StreamError::EventStream(io.to_string()),
382        )));
383        let provider = error.provider().expect("expected provider error");
384        assert_eq!(provider.kind, ProviderErrorKind::StreamInterrupted);
385        assert!(error.is_retryable());
386    }
387
388    #[test]
389    fn async_openai_non_error_body_stays_a_json_parsing_error() {
390        let body = r#"{"id":"chatcmpl-1","object":"chat.completion","choices":[]}"#;
391        let parse_error = serde_json::from_str::<String>(body).unwrap_err();
392
393        let error = LlmError::from(async_openai::error::OpenAIError::JSONDeserialize(parse_error, body.to_string()));
394
395        assert!(matches!(error, LlmError::JsonParsing(_)), "got {error:?}");
396        assert!(!error.is_retryable());
397    }
398}
llm/error.rs

llm/
error.rs
