Enum Error 

#[non_exhaustive]
pub enum Error {
    AgentInitialization(String),
    AgentExecution(String),
    Serialization(String),
    Content(String),
    Tool(String),
    Service(String),
    ServiceStatus {
        status: u16,
        message: String,
        retry_after: Option<f64>,
    },
    ServiceInvalidAuth {
        message: String,
    },
    ServiceInvalidRequest {
        message: String,
    },
    ServiceContentFilter {
        message: String,
    },
    MiddlewareFailure(String),
    Workflow(String),
    AdditionItemMismatch(String),
    Configuration(String),
    Json(Error),
    Other(String),
}

The primary error type for the agent framework.

This mirrors the exception hierarchy used by the Python agent_framework.exceptions module while remaining idiomatic Rust.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

AgentInitialization(String)

An error occurred while initializing an agent.

AgentExecution(String)

An error occurred while executing an agent run.

Serialization(String)

An error occurred while (de)serializing a value.

Content(String)

A content item could not be parsed or was of an unknown type.

Tool(String)

A tool/function invocation failed.

Service(String)

A chat client / service returned an error.

Used for non-HTTP service failures (transport errors, stream-decode errors, in-body error payloads on an otherwise-successful response). For a non-success HTTP status, prefer Error::ServiceStatus, which also carries the status code and any Retry-After.

ServiceStatus

A chat client / service returned a non-success HTTP status.

Distinct from Error::Service so a retry layer can inspect the numeric status code and any server-advised Retry-After delay (in seconds). Displays like Error::Service (a service error: ... message), with the status code folded into the message.

This is the fallback classification for a non-success status that isn’t one of the more specific variants below (notably 408/429/ 5xx, which a retry layer treats as transient) — see Error::ServiceInvalidAuth, Error::ServiceInvalidRequest, and Error::ServiceContentFilter for statuses a provider client can classify more precisely.

Fields

status: u16

The HTTP status code returned by the service.

message: String

A human-readable message (typically the response body).

retry_after: Option<f64>

The server-advised retry delay in seconds, parsed from the Retry-After header when present.

ServiceInvalidAuth

The service rejected the request due to missing or invalid credentials (typically HTTP 401/403).

Mirrors upstream’s ServiceInvalidAuthError. Like Error::Service, this carries no status code of its own (the numeric status, when known, is folded into the message by the provider client) — it exists so callers, and the default retry policy, can treat authentication / authorization failures as definitively non-transient without inspecting a status code themselves. Never retried by RetryOn::Default.

Fields

message: String

A human-readable message (typically the response body).

ServiceInvalidRequest

The service rejected the request as malformed or otherwise invalid (typically HTTP 400/404/422) for a reason other than content filtering.

Mirrors upstream’s ServiceInvalidRequestError. See Error::ServiceContentFilter for the content-filter-specific case. Never retried by RetryOn::Default — a request that was rejected as invalid will be rejected again unchanged.

Fields

message: String

A human-readable message (typically the response body).

ServiceContentFilter

The service refused the request (or part of a response) because it tripped a content filter / moderation policy.

Mirrors upstream’s ServiceContentFilterException (OpenAIContentFilterException for OpenAI/Azure OpenAI specifically). Never retried by RetryOn::Default — the content, not the service, is the problem.

Fields

message: String

A human-readable message (typically the response body).

MiddlewareFailure(String)

Function middleware signalled an unrecoverable failure: the run must stop rather than continue with a tool-error result.

The function-invocation loop absorbs every other error a tool or its middleware produces into a FunctionResultContent { exception, .. }, hands it back to the model, and keeps looping — the right default for an ordinary tool failure the model can recover from or route around. An enforcement layer (a guardrail, a policy check, an authorization gate) needs the opposite: when it refuses a call, the run must fail closed, not hand the model an error string and let it try again.

Middleware returning this variant gets that fail-closed escape. It is the only error the loop propagates instead of absorbing; when one of a parallel batch of calls raises it, the batch’s in-flight siblings are dropped (cancelled) and the failure surfaces from the run. Mirrors upstream’s MiddlewareFailure exception (Python #7562).

The signal is carried by the error type, not by who produced it, so a tool executor that returns this variant is propagated the same way. Middleware that wants the ordinary absorb-and-continue contract should keep returning any other variant — Error::Tool is the usual choice.

Workflow(String)

A workflow validation or execution error.

AdditionItemMismatch(String)

Two streamed content items could not be merged (mismatched ids).

Configuration(String)

A required configuration value was missing or invalid.

Json(Error)

An underlying JSON error.

Other(String)

Any other error, wrapping a boxed source.

Implementations

impl Error

pub fn other(msg: impl Display) -> Error

Create an Error::Other from anything displayable.

pub fn service(msg: impl Display) -> Error

Create an Error::Service from anything displayable.

pub fn service_status( status: u16, msg: impl Display, retry_after: Option<f64>, ) -> Error

Create an Error::ServiceStatus from an HTTP status code, a message, and an optional Retry-After delay (in seconds).

pub fn service_invalid_auth(msg: impl Display) -> Error

Create an Error::ServiceInvalidAuth from anything displayable.

pub fn service_invalid_request(msg: impl Display) -> Error

Create an Error::ServiceInvalidRequest from anything displayable.

pub fn service_content_filter(msg: impl Display) -> Error

Create an Error::ServiceContentFilter from anything displayable.

pub fn status(&self) -> Option<u16>

The HTTP status code carried by this error, if it is an Error::ServiceStatus.

pub fn retry_after(&self) -> Option<f64>

The server-advised retry delay in seconds, if this is an Error::ServiceStatus that carried a Retry-After header.

pub fn tool(msg: impl Display) -> Error

Create an Error::Tool from anything displayable.

pub fn middleware_failure(msg: impl Display) -> Error

Create an Error::MiddlewareFailure from anything displayable: the fail-closed signal function middleware returns to stop a run outright instead of having its error absorbed into a tool-error result.

pub fn is_middleware_failure(&self) -> bool

Whether this error is the Error::MiddlewareFailure fail-closed signal, which the function-invocation loop propagates rather than absorbing into a tool-error result.

Trait Implementations

impl Debug for Error

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

Formats the value using the given formatter.

impl Display for Error

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

Formats the value using the given formatter.

impl Error for Error

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 Error

fn from(source: Error) -> Error

Converts to this type from the input type.