Trait CapabilityError

Source

pub trait CapabilityError:
    Error
    + Send
    + Sync {
    // Required methods
    fn category(&self) -> ErrorCategory;
    fn is_transient(&self) -> bool;
    fn is_retryable(&self) -> bool;
    fn retry_after(&self) -> Option<Duration>;
}

Expand description

Shared classification interface for capability errors.

All capability-specific error types (e.g., LlmError, RecallError, StoreError) implement this trait to enable uniform error handling across the system.

§Semantic Distinction: Transient vs Retryable

is_transient(): The underlying condition may clear without changing the request. Examples: rate limiting (quota resets), timeout (server was busy), network blip.
is_retryable(): It makes sense to retry the operation given typical idempotency. Examples: transient errors are usually retryable, but also conflicts (re-fetch and retry with updated version), or certain auth errors (token expired, can refresh).

These often overlap but serve different purposes:

A circuit breaker cares about transient errors (to detect unhealthy backends).
A retry loop cares about retryable errors (to know whether to attempt again).

§Implementation Notes

All implementations must also implement std::error::Error and be Send + Sync to ensure thread-safe error handling in async contexts.

§Example

impl CapabilityError for MyError {
    fn category(&self) -> ErrorCategory {
        match self {
            Self::TimedOut => ErrorCategory::Timeout,
            Self::BadInput(_) => ErrorCategory::InvalidInput,
            // ...
        }
    }

    fn is_transient(&self) -> bool {
        matches!(self.category(), ErrorCategory::Timeout | ErrorCategory::Unavailable)
    }

    fn is_retryable(&self) -> bool {
        self.is_transient() || matches!(self.category(), ErrorCategory::Conflict)
    }

    fn retry_after(&self) -> Option<Duration> {
        None // Override when rate limit info available
    }
}

Required Methods§

Source

fn category(&self) -> ErrorCategory

Returns the category of this error for generic handling.

Categories enable middleware to operate without knowing specific error types.

Source

fn is_transient(&self) -> bool

Returns true if the underlying condition may clear without changing the request.

Transient errors indicate temporary conditions like rate limiting, network issues, or service overload. Circuit breakers use this to detect unhealthy backends.

Source