Enum SdkError 

#[non_exhaustive]
pub enum SdkError {
    ModelNotFound {
        model_id: String,
    },
    ProviderNotFound {
        provider: String,
    },
    AllProvidersExhausted {
        attempts: usize,
    },
    ModelExcluded {
        model_id: String,
    },
    AgentNotRunnable {
        agent_id: String,
        status: String,
    },
    AgentAlreadyRunning {
        agent_id: String,
    },
    SnapshotNotFound {
        agent_id: String,
    },
    SnapshotCorrupt {
        agent_id: String,
        reason: String,
    },
    PermissionDenied {
        subject: String,
        capability: String,
    },
    CapabilityExpired {
        subject: String,
    },
    WorkItemNotFound {
        item_id: String,
    },
    VersionConflict {
        key: String,
        expected: u64,
        current: u64,
    },
    VoteNotFound {
        vote_id: String,
    },
    InvalidState {
        entity: String,
        reason: String,
    },
    MiddlewareBlocked {
        middleware: String,
        reason: String,
    },
    TokenBudgetExceeded {
        used: usize,
        budget: usize,
    },
    CostBudgetExceeded {
        used: f64,
        budget: f64,
    },
    RoutingDisabled,
    NoRouteAvailable {
        model_id: String,
    },
    ExecutionFailed {
        reason: String,
    },
    GroupExecutionFailed {
        failed: usize,
        total: usize,
    },
    Cancelled,
    PortNotConfigured {
        port: &'static str,
    },
    UnknownScheme {
        scheme: String,
    },
    Io(Error),
    Serialization {
        context: &'static str,
        source: Error,
    },
    AlreadyExists {
        key: String,
    },
    CatalogUnavailable {
        reason: String,
    },
    CatalogOverrideParse {
        path: String,
        reason: String,
    },
    CatalogRefresh {
        reason: String,
    },
    Internal(Error),
}

oxicode-sdk structured error type.

SDK consumers can use match to handle specific error cases. Internal implementations may still use anyhow, converted at public API boundaries. #[non_exhaustive] — consumers MUST add a catch-all _ => arm in their match expressions so that new variants added in future minor releases do not break compilation. Existing named variants are frozen; their meaning does not change between releases (see docs/release-process.md).

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.

ModelNotFound

The requested model could not be resolved by any configured provider.

Fields

model_id: String

Identifier of the model that was requested.

ProviderNotFound

No provider matching the requested name is registered with the SDK.

Fields

provider: String

Name of the provider that was requested.

AllProvidersExhausted

Every provider in the failover chain was attempted and failed.

Fields

attempts: usize

Number of provider attempts made before giving up.

ModelExcluded

The model exists but is excluded from resolution by routing control.

Fields

model_id: String

Identifier of the excluded model.

AgentNotRunnable

The agent exists but cannot run in its current lifecycle status.

Fields

agent_id: String

Identifier of the agent.

status: String

Current lifecycle status of the agent.

AgentAlreadyRunning

An attempt was made to start an agent that is already running.

Fields

agent_id: String

Identifier of the agent.

SnapshotNotFound

No persisted snapshot could be found for the agent.

Fields

agent_id: String

Identifier of the agent whose snapshot was requested.

SnapshotCorrupt

A persisted snapshot exists but failed integrity validation.

Fields

agent_id: String

Identifier of the agent whose snapshot is corrupt.

reason: String

Human-readable explanation of the corruption.

PermissionDenied

The principal lacks a required capability for the requested action.

Fields

subject: String

The principal (agent, user, or component) requesting access.

capability: String

The capability that would be required to permit the action.

CapabilityExpired

A previously granted capability has expired and is no longer valid.

Fields

subject: String

The principal whose capability expired.

WorkItemNotFound

A referenced coordination work item does not exist.

Fields

item_id: String

Identifier of the missing work item.

VersionConflict

An optimistic-concurrency guard detected a stale version of a value.

Fields

key: String

The key whose version was in conflict.

expected: u64

Version the caller expected to observe.

current: u64

Version currently stored.

VoteNotFound

A referenced vote session could not be found.

Fields

vote_id: String

Identifier of the missing vote session.

InvalidState

A state-machine precondition was violated (wrong status for the operation).

Fields

entity: String

The entity whose state was invalid.

reason: String

Why the transition was rejected.

MiddlewareBlocked

A middleware intercepted and blocked the request.

Fields

middleware: String

Name of the middleware that blocked the request.

reason: String

Why the middleware blocked the request.

TokenBudgetExceeded

The configured token-usage budget for a run was exceeded.

Fields

used: usize

Number of tokens consumed so far.

budget: usize

Maximum number of tokens permitted by the budget.

CostBudgetExceeded

The configured monetary cost budget for a run was exceeded.

Fields

used: f64

Cost consumed so far, in currency units.

budget: f64

Maximum cost permitted by the budget.

RoutingDisabled

Routing is disabled in the current configuration.

NoRouteAvailable

No route could be determined for the requested model.

Fields

model_id: String

Identifier of the model for which no route exists.

ExecutionFailed

A single agent’s execution failed.

Fields

reason: String

Human-readable reason for the failure.

GroupExecutionFailed

One or more agents in a group run failed.

Fields

failed: usize

Number of agents in the group that failed.

total: usize

Total number of agents in the group.

Cancelled

The run was cancelled before completing.

PortNotConfigured

A required port was never configured on the builder.

Fields

port: &'static str

Name of the missing port.

UnknownScheme

A URL scheme has no registered handler.

Fields

scheme: String

The unrecognized URL scheme.

Io(Error)

A file-system or device I/O error in a port adapter.

Serialization

A serialization or deserialization failure.

Fields

context: &'static str

“encode” or “decode”.

source: Error

The underlying serde error.

AlreadyExists

An entry with the same key or path already exists.

Fields

key: String

The duplicate key or path.

CatalogUnavailable

The catalog port is not wired or returned no data for the request.

Fields

reason: String

Why the catalog was unavailable.

CatalogOverrideParse

A user-supplied catalog override file failed to parse.

Fields

path: String

Path to the override file that failed to parse.

reason: String

Why the override file could not be parsed.

CatalogRefresh

A catalog refresh attempt failed (network, HTTP, or parse error). The stale snapshot is still served; this error is informational.

Fields

reason: String

Why the refresh attempt failed.

Internal(Error)

An unexpected internal error, converted from an anyhow::Error.

Implementations

impl SdkError

pub fn is_internal(&self) -> bool

Returns true if this is an internal/unexpected error.

Trait Implementations

impl Debug for SdkError

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

Formats the value using the given formatter.

impl Display for SdkError

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

Formats the value using the given formatter.

impl Error for SdkError

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 SdkError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for SdkError

fn from(source: Error) -> Self

Converts to this type from the input type.