Enum ToolError 

pub enum ToolError {
    Retriable {
        source: Option<Arc<dyn Error + Send + Sync>>,
        source_message: String,
        context: String,
    },
    RateLimited {
        source: Option<Arc<dyn Error + Send + Sync>>,
        source_message: String,
        context: String,
        retry_after: Option<Duration>,
    },
    Permanent {
        source: Option<Arc<dyn Error + Send + Sync>>,
        source_message: String,
        context: String,
    },
    InvalidInput {
        source: Option<Arc<dyn Error + Send + Sync>>,
        source_message: String,
        context: String,
    },
    SignerContext(String),
}

Tool-specific error type for distinguishing retriable vs permanent failures.

Variants

Retriable

Operation can be retried

Fields

source: Option<Arc<dyn Error + Send + Sync>>

The typed error source (not serialized)

source_message: String

The error message for serialization

context: String

Additional context about the error

RateLimited

Rate limited, retry after delay

Fields

source: Option<Arc<dyn Error + Send + Sync>>

The typed error source (not serialized)

source_message: String

The error message for serialization

context: String

Additional context about the rate limiting

retry_after: Option<Duration>

Optional duration to wait before retrying (in seconds)

Permanent

Permanent error, do not retry

Fields

source: Option<Arc<dyn Error + Send + Sync>>

The typed error source (not serialized)

source_message: String

The error message for serialization

context: String

Additional context about the permanent error

InvalidInput

Invalid input provided

Fields

source: Option<Arc<dyn Error + Send + Sync>>

The typed error source (not serialized)

source_message: String

The error message for serialization

context: String

Description of what input was invalid

SignerContext(String)

Signer context error

Implementations

impl ToolError

pub fn retriable_with_source<E: Error + Send + Sync + 'static>( source: E, context: impl Into<String>, ) -> Self

Creates a retriable error with context and source preservation

pub fn permanent_with_source<E: Error + Send + Sync + 'static>( source: E, context: impl Into<String>, ) -> Self

Creates a permanent error with context and source preservation

pub fn rate_limited_with_source<E: Error + Send + Sync + 'static>( source: E, context: impl Into<String>, retry_after: Option<Duration>, ) -> Self

Creates a rate limited error with optional retry duration

pub fn invalid_input_with_source<E: Error + Send + Sync + 'static>( source: E, context: impl Into<String>, ) -> Self

Creates an invalid input error

pub const fn is_retriable(&self) -> bool

Returns whether this error is retriable

pub const fn retry_after(&self) -> Option<Duration>

Returns the retry delay if this is a rate limited error

pub const fn is_rate_limited(&self) -> bool

Checks if the error is rate limited (for compatibility)

pub fn retriable_string<S: Into<String>>(msg: S) -> Self

Creates a retriable error from a string message

pub fn permanent_string<S: Into<String>>(msg: S) -> Self

Creates a permanent error from a string message

pub fn rate_limited_string<S: Into<String>>(msg: S) -> Self

Creates a rate limited error from a string message

pub fn invalid_input_string<S: Into<String>>(msg: S) -> Self

Creates an invalid input error from a string message

pub fn contains(&self, needle: &str) -> bool

Check if the error contains a specific substring in its string representation

pub fn retriable_from_error<E: Error + Send + Sync + 'static>( source: E, context: impl Into<String>, ) -> Self

Creates a retriable error from any error type.

pub fn permanent_from_error<E: Error + Send + Sync + 'static>( source: E, context: impl Into<String>, ) -> Self

Creates a permanent error from any error type.

Trait Implementations

impl Clone for ToolError

fn clone(&self) -> ToolError

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ToolError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ToolError

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for ToolError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for ToolError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for ToolError

Error Classification: Explicit is Better

Generic From implementations for common error types like anyhow::Error and String have been intentionally removed. This is a deliberate design choice to enforce explicit error classification at the point of creation.

Automatically classifying unknown errors as Permanent is a safe default but can hide bugs where transient, retriable errors are not handled correctly. By requiring explicit classification, developers are forced to make a conscious decision about the nature of the error.

Best Practices

Always use the explicit constructors to create ToolError instances:

use riglr_core::ToolError;
use std::io::Error as IoError;

// ✅ Explicitly classify known transient errors as retriable.
let network_error = IoError::new(std::io::ErrorKind::TimedOut, "Connection timeout");
let tool_error = ToolError::retriable_with_source(network_error, "API call failed");

// ✅ Explicitly classify rate limiting errors.
let rate_limit_error = IoError::new(std::io::ErrorKind::Other, "Rate limited");
let tool_error = ToolError::rate_limited_with_source(
    rate_limit_error,
    "API rate limit exceeded",
    Some(std::time::Duration::from_secs(60))
);

// ✅ Explicitly classify user input errors.
let input_error = IoError::new(std::io::ErrorKind::InvalidInput, "Bad address");
let tool_error = ToolError::invalid_input_with_source(input_error, "Invalid address format");

// ✅ Explicitly classify all other unrecoverable errors as permanent.
let auth_error = IoError::new(std::io::ErrorKind::PermissionDenied, "Invalid API key");
let tool_error = ToolError::permanent_with_source(auth_error, "Authentication failed");

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<SignerError> for ToolError

fn from(err: SignerError) -> Self

Converts to this type from the input type.

impl PartialEq for ToolError

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for ToolError

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.