Skip to main content

graphrt_llm/
error.rs

1//! Model errors and their mapping to node errors.
2
3use graphrt_core::NodeError;
4
5/// Error raised by a model provider.
6#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
7#[non_exhaustive]
8pub enum LlmError {
9    /// Invalid or missing credentials / permissions.
10    #[error("authentication failed: {0}")]
11    Auth(String),
12    /// Too many requests. `retry_after_ms` comes from the provider's `retry-after` header.
13    #[error("rate limited: {message}")]
14    RateLimit { message: String, retry_after_ms: Option<u64> },
15    /// The prompt does not fit into the model's context window.
16    #[error("context length exceeded: {0}")]
17    ContextLength(String),
18    /// The provider rejected the request (invalid parameters, unknown model...).
19    #[error("bad request: {0}")]
20    BadRequest(String),
21    /// Provider-side failure (5xx, overloaded).
22    #[error("server error ({status}): {message}")]
23    Server { status: u16, message: String },
24    /// Connection, TLS or timeout failure.
25    #[error("network error: {0}")]
26    Network(String),
27    /// The response could not be decoded.
28    #[error("invalid response: {0}")]
29    Decode(String),
30    /// Local misconfiguration (unknown provider, missing API key...).
31    #[error("configuration error: {0}")]
32    Config(String),
33}
34
35impl LlmError {
36    /// Whether retrying the same request may succeed.
37    pub fn is_retryable(&self) -> bool {
38        matches!(
39            self,
40            LlmError::RateLimit { .. } | LlmError::Server { .. } | LlmError::Network(_) | LlmError::Decode(_)
41        )
42    }
43
44    /// Stable machine-readable kind.
45    pub fn kind(&self) -> &'static str {
46        match self {
47            LlmError::Auth(_) => "model_auth",
48            LlmError::RateLimit { .. } => "model_rate_limit",
49            LlmError::ContextLength(_) => "model_context_length",
50            LlmError::BadRequest(_) => "model_bad_request",
51            LlmError::Server { .. } => "model_server",
52            LlmError::Network(_) => "model_network",
53            LlmError::Decode(_) => "model_decode",
54            LlmError::Config(_) => "model_config",
55        }
56    }
57
58    /// Classify an HTTP error response.
59    pub fn from_status(status: u16, body: &str, retry_after_ms: Option<u64>) -> Self {
60        let message = summarize_body(body);
61        let lowered = body.to_ascii_lowercase();
62        match status {
63            401 | 403 => LlmError::Auth(message),
64            429 => LlmError::RateLimit { message, retry_after_ms },
65            408 => LlmError::Network(message),
66            400 | 404 | 413 | 422
67                if lowered.contains("context_length")
68                    || lowered.contains("context length")
69                    || lowered.contains("maximum context")
70                    || lowered.contains("prompt is too long")
71                    || lowered.contains("too many tokens") =>
72            {
73                LlmError::ContextLength(message)
74            }
75            413 => LlmError::ContextLength(message),
76            s if s >= 500 => LlmError::Server { status: s, message },
77            _ => LlmError::BadRequest(message),
78        }
79    }
80}
81
82/// Extract a readable message from an error body, capped in length.
83fn summarize_body(body: &str) -> String {
84    const MAX: usize = 1000;
85    let parsed: Option<String> = serde_json::from_str::<serde_json::Value>(body).ok().and_then(|v| {
86        let err = v.get("error").unwrap_or(&v);
87        err.get("message").and_then(|m| m.as_str()).map(str::to_owned).or_else(|| err.as_str().map(str::to_owned))
88    });
89    let text = parsed.unwrap_or_else(|| body.trim().to_owned());
90    if text.chars().count() > MAX {
91        let mut cut: String = text.chars().take(MAX).collect();
92        cut.push('…');
93        cut
94    } else {
95        text
96    }
97}
98
99impl From<LlmError> for NodeError {
100    fn from(e: LlmError) -> Self {
101        let kind = e.kind();
102        let mut message = e.to_string();
103        if let LlmError::RateLimit { retry_after_ms: Some(ms), .. } = &e {
104            message.push_str(&format!(" (retry after {ms} ms)"));
105        }
106        let retry_after_ms = match &e {
107            LlmError::RateLimit { retry_after_ms, .. } => *retry_after_ms,
108            _ => None,
109        };
110        let error = if e.is_retryable() { NodeError::new(kind, message) } else { NodeError::fatal(kind, message) };
111        error.with_retry_after(retry_after_ms)
112    }
113}
114
115#[cfg(test)]
116mod tests {
117    use super::*;
118
119    #[test]
120    fn classification() {
121        assert!(matches!(LlmError::from_status(401, "", None), LlmError::Auth(_)));
122        let rl = LlmError::from_status(429, r#"{"error":{"message":"slow down"}}"#, Some(2000));
123        assert_eq!(rl, LlmError::RateLimit { message: "slow down".into(), retry_after_ms: Some(2000) });
124        assert!(rl.is_retryable());
125        let ctx =
126            LlmError::from_status(400, r#"{"error":{"code":"context_length_exceeded","message":"too long"}}"#, None);
127        assert!(matches!(ctx, LlmError::ContextLength(_)));
128        assert!(!ctx.is_retryable());
129        assert!(matches!(LlmError::from_status(400, "nope", None), LlmError::BadRequest(_)));
130        assert!(matches!(LlmError::from_status(529, "overloaded", None), LlmError::Server { status: 529, .. }));
131    }
132
133    #[test]
134    fn node_error_retryability() {
135        let n: NodeError = LlmError::Server { status: 500, message: "x".into() }.into();
136        assert!(n.retryable);
137        assert_eq!(n.kind, "model_server");
138        let n: NodeError = LlmError::BadRequest("x".into()).into();
139        assert!(!n.retryable);
140        let n: NodeError = LlmError::RateLimit { message: "x".into(), retry_after_ms: Some(5) }.into();
141        assert!(n.message.contains("retry after 5 ms"));
142    }
143}