Skip to main content

graphrt_rag/
error.rs

1//! Errors raised by retrieval components.
2
3use graphrt_core::NodeError;
4
5/// Error from an embedder, store, reranker or retriever.
6#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
7#[non_exhaustive]
8pub enum RagError {
9    /// Invalid configuration (missing dataset, bad URL, unknown provider...).
10    #[error("configuration error: {0}")]
11    Config(String),
12    /// Invalid request input (empty query, dimension mismatch...).
13    #[error("invalid input: {0}")]
14    Input(String),
15    /// Credentials were rejected.
16    #[error("authentication failed: {0}")]
17    Auth(String),
18    /// The provider is rate limiting requests.
19    #[error("rate limited: {message}")]
20    RateLimit { message: String, retry_after_ms: Option<u64> },
21    /// Non-success HTTP status not covered by a more specific variant.
22    #[error("HTTP {status}: {message}")]
23    Http { status: u16, message: String },
24    /// Connection / transport 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    /// Vector store failure.
31    #[error("store error: {0}")]
32    Store(String),
33    /// Unknown dataset or document.
34    #[error("not found: {0}")]
35    NotFound(String),
36    /// Local persistence failure.
37    #[error("I/O error: {0}")]
38    Io(String),
39    /// An in-process model could not be loaded or run (missing or corrupt files,
40    /// unsupported architecture, inference failure).
41    #[error("embedding model error: {0}")]
42    Model(String),
43    /// The dataset or store does not support this operation (e.g. listing the
44    /// documents of an external retriever).
45    #[error("not supported: {0}")]
46    Unsupported(String),
47}
48
49impl RagError {
50    /// Whether retrying the same request may succeed.
51    pub fn is_retryable(&self) -> bool {
52        match self {
53            RagError::RateLimit { .. } | RagError::Network(_) => true,
54            RagError::Http { status, .. } => *status >= 500 || *status == 408,
55            _ => false,
56        }
57    }
58
59    /// Short machine-readable category.
60    pub fn kind(&self) -> &'static str {
61        match self {
62            RagError::Config(_) => "config",
63            RagError::Input(_) => "invalid_input",
64            RagError::Auth(_) => "auth",
65            RagError::RateLimit { .. } => "rate_limit",
66            RagError::Http { .. } => "http_status",
67            RagError::Network(_) => "network",
68            RagError::Decode(_) => "invalid_response",
69            RagError::Store(_) => "store",
70            RagError::NotFound(_) => "not_found",
71            RagError::Io(_) => "io",
72            RagError::Model(_) => "model",
73            RagError::Unsupported(_) => "unsupported",
74        }
75    }
76}
77
78impl From<RagError> for NodeError {
79    fn from(e: RagError) -> Self {
80        let retry_after = match &e {
81            RagError::RateLimit { retry_after_ms, .. } => *retry_after_ms,
82            _ => None,
83        };
84        let base = if e.is_retryable() {
85            NodeError::new(e.kind(), e.to_string())
86        } else {
87            NodeError::fatal(e.kind(), e.to_string())
88        };
89        base.with_retry_after(retry_after)
90    }
91}
92
93#[cfg(test)]
94mod tests {
95    use super::*;
96
97    #[test]
98    fn retryable_mapping() {
99        assert!(RagError::Network("x".into()).is_retryable());
100        assert!(RagError::Http { status: 503, message: String::new() }.is_retryable());
101        assert!(!RagError::Http { status: 400, message: String::new() }.is_retryable());
102        let ne: NodeError = RagError::RateLimit { message: "slow".into(), retry_after_ms: Some(1500) }.into();
103        assert!(ne.retryable);
104        assert_eq!(ne.retry_after_ms, Some(1500));
105        let ne: NodeError = RagError::Auth("bad key".into()).into();
106        assert!(!ne.retryable);
107    }
108}