Struct ToolFailure 

#[non_exhaustive]
pub struct ToolFailure {
    pub kind: ToolFailureKind,
    pub message: String,
    pub retryable: Option<bool>,
    pub code: Option<String>,
    pub http_status: Option<u16>,
}

A structured, model-independent description of a tool execution failure.

This is the “machine-visible” half of a failed tool call. The model-visible text lives separately on ToolExecutionResult::model_output; this carries the classification a hook or policy acts on. Build one with the per-kind constructors (which pre-fill a sensible retryable default) and refine it with the builder setters:

use rig_core::tool::{ToolFailure, ToolFailureKind};

let failure = ToolFailure::not_found("user 42 does not exist")
    .with_http_status(404)
    .with_code("USER_NOT_FOUND");
assert_eq!(failure.kind, ToolFailureKind::NotFound);
assert_eq!(failure.retryable, Some(false));
assert_eq!(failure.http_status, Some(404));

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

kind: ToolFailureKind

The standard classification of the failure.

message: String

A human-readable description of what went wrong. This is not automatically shown to the model — it is metadata for logs and policies.

retryable: Option<bool>

Whether retrying the call could plausibly succeed. None means unknown.

code: Option<String>

An optional machine-readable error code (e.g. a provider error code).

http_status: Option<u16>

An optional HTTP status code, when the failure originated from an HTTP call.

Implementations

impl ToolFailure

pub fn new(kind: ToolFailureKind, message: impl Into<String>) -> Self

Construct a failure of the given kind with message. retryable, code, and http_status start unset — use the builder setters or a per-kind constructor to fill them.

pub fn invalid_args(message: impl Into<String>) -> Self

An InvalidArgs failure.

pub fn timeout(message: impl Into<String>) -> Self

A Timeout failure.

pub fn cancelled(message: impl Into<String>) -> Self

A Cancelled failure.

pub fn not_found(message: impl Into<String>) -> Self

A NotFound failure.

pub fn permission_denied(message: impl Into<String>) -> Self

A PermissionDenied failure.

pub fn rate_limited(message: impl Into<String>) -> Self

A RateLimited failure.

pub fn provider(message: impl Into<String>) -> Self

A Provider failure.

pub fn network(message: impl Into<String>) -> Self

A Network failure.

pub fn other(message: impl Into<String>) -> Self

An Other failure — the catch-all.

pub fn with_retryable(self, retryable: bool) -> Self

Set whether the failure is retryable.

pub fn with_code(self, code: impl Into<String>) -> Self

Set a machine-readable error code.

pub fn with_http_status(self, status: u16) -> Self

Set the originating HTTP status code.

Trait Implementations

impl Clone for ToolFailure

fn clone(&self) -> ToolFailure

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ToolFailure

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

Formats the value using the given formatter.

impl Display for ToolFailure

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

Formats the value using the given formatter.

impl Eq for ToolFailure

impl Error for ToolFailure

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 PartialEq for ToolFailure

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for ToolFailure