Enum AgentError 

pub enum AgentError {
    ProcessFailed {
        exit_code: i32,
        stderr: String,
    },
    SchemaValidation {
        expected: String,
        got: String,
        debug_messages: Vec<DebugMessage>,
        partial_usage: Box<PartialUsage>,
        raw_response: Option<String>,
    },
    BudgetExceeded {
        spent_usd: f64,
        limit_usd: f64,
        debug_messages: Vec<DebugMessage>,
        partial_usage: Box<PartialUsage>,
    },
    Api {
        status: Option<u16>,
        code: Option<String>,
        message: String,
    },
    PromptTooLarge {
        chars: usize,
        estimated_tokens: usize,
        model_limit: usize,
    },
    Timeout {
        limit: Duration,
    },
    RateLimited {
        provider: String,
        retry_after_secs: Option<u64>,
    },
    HttpProvider {
        provider: String,
        status_code: u16,
        message: String,
    },
    UnknownToolProfile {
        profile: String,
        available: Vec<String>,
    },
    ToolProfileUnsupported {
        provider: String,
        profile: String,
    },
    NoCapacity {
        kind: String,
        next_reset: Option<DateTime<Utc>>,
    },
    CapacityWait {
        kind: String,
        wake_at: DateTime<Utc>,
    },
    AccountNotFound {
        name: String,
    },
}

Error specific to agent (AI provider) invocations.

Returned by AgentProvider::invoke and automatically wrapped into OperationError::Agent when propagated with ?.

Variants

ProcessFailed

The agent process exited with a non-zero status code.

Fields

exit_code: i32

Process exit code, or -1 if spawning failed.

stderr: String

Captured stderr.

SchemaValidation

The agent output did not match the expected schema.

Fields

expected: String

What was expected (e.g. "structured_output field").

got: String

What was actually received.

debug_messages: Vec<DebugMessage>

Verbose conversation trace captured before the validation failure.

Populated when the agent ran in verbose (stream-json) mode so that callers can persist the debug trail even on error paths.

partial_usage: Box<PartialUsage>

Partial usage data from the CLI response, available even though structured output extraction failed. Boxed to keep AgentError small on the stack.

raw_response: Option<String>

Raw text response from the agent, truncated to ~4000 bytes.

When structured output extraction fails, the model may still have produced useful text in the result field. This captures it so callers can persist it for debugging (e.g. in the step output).

BudgetExceeded

The agent stopped because it exhausted its configured USD budget.

Distinct from SchemaValidation: retrying costs money and cannot succeed, since the budget is already spent. Treated as non-retryable by is_retryable at the operation level and by the engine at the run level.

Fields

spent_usd: f64

Total cost reported by the provider before it stopped, in USD.

limit_usd: f64

The configured max_budget_usd limit, in USD.

debug_messages: Vec<DebugMessage>

Verbose conversation trace captured before the budget ran out.

partial_usage: Box<PartialUsage>

Usage data reported alongside the budget error. Boxed to keep AgentError small on the stack.

Api

The model API refused the request the Claude CLI sent.

Built from a CLI result with is_error: true: the CLI reached the API, got an error back and wrote it in place of an answer. Structured output is never validated against it. is_retryable retries it only when status is absent, 429 or 5xx (529 overloaded included): a 4xx such as claude_code_version_too_old or an unknown model fails the same way on every attempt.

Examples

use ironflow_core::error::AgentError;

let err = AgentError::Api {
    status: Some(400),
    code: Some("claude_code_version_too_old".to_string()),
    message: "API Error: 400 Claude Code 2.1.274 does not support this model".to_string(),
};
assert!(err.to_string().contains("claude_code_version_too_old"));

Fields

status: Option<u16>

HTTP status the API answered with (api_error_status), absent when the CLI did not report one.

code: Option<String>

API error code reported by the CLI (api_error_code), e.g. "claude_code_version_too_old".

message: String

Error message printed by the CLI (its result field).

PromptTooLarge

The prompt exceeds the model’s context window.

Returned before spawning the process when the estimated token count exceeds the model’s known limit.

• chars - number of characters in the combined prompt (system + user).
• estimated_tokens - approximate token count (chars / 4).
• model_limit - the model’s context window in tokens.

Fields

chars: usize

Number of characters in the prompt.

estimated_tokens: usize

Estimated token count (chars / 4 heuristic).

model_limit: usize

Model’s context window in tokens.

Timeout

The agent did not complete within the configured timeout.

Fields

limit: Duration

The Duration that was exceeded.

RateLimited

The provider returned HTTP 429 Too Many Requests.

Fields

provider: String

Provider name (e.g. "openai", "anthropic").

retry_after_secs: Option<u64>

Value from the Retry-After header, if present.

HttpProvider

The provider returned an unexpected HTTP error or a transport-level failure.

When status_code is 0, no HTTP response was received (connection failure, DNS resolution error, TLS handshake failure, or response body read error).

Fields

provider: String

Provider name (e.g. "openai", "nvidia").

status_code: u16

HTTP status code, or 0 for transport-level failures.

message: String

Error message from the provider response body, or transport error description.

UnknownToolProfile

The step asked for a tool profile the provider does not have.

Never falls back to other tools: a typo must not widen what the model can do. Deterministic, so never retried.

Fields

profile: String

The profile the step asked for.

available: Vec<String>

Profiles registered on the provider, sorted.

ToolProfileUnsupported

The step asked for a tool profile, but the provider cannot apply one.

Claude CLI providers pick their tools with allowed_tools and MCP configuration; they refuse a profile rather than ignore it.

Fields

provider: String

Provider that refused the profile (e.g. "claude-code").

profile: String

The profile the step asked for.

NoCapacity

No provider account can run the step, and the run will not wait for one.

Returned when every targeted account (or the worker’s own token) is rate limited and the next reset is unknown or further away than the step’s max_capacity_wait, or when that wait is Duration::ZERO (fast fail). Never retried: replaying it at once hits the same limits.

Examples

use ironflow_core::error::AgentError;

let err = AgentError::NoCapacity {
    kind: "claude".to_string(),
    next_reset: None,
};
assert!(err.to_string().contains("no capacity for claude"));

Fields

kind: String

Provider kind the step needed (e.g. "claude").

next_reset: Option<DateTime<Utc>>

Earliest moment a targeted rate limit window resets, when known.

CapacityWait

Not a failure: asks the engine to suspend the run until wake_at.

Returned by the account-aware provider when every targeted account is rate limited but capacity comes back within the step’s max_capacity_wait. The engine puts the run to sleep and re-executes the step from zero when it wakes, or earlier when an account of kind is added, re-enabled or gets a new token. Never retried.

Examples

use chrono::Utc;
use ironflow_core::error::AgentError;

let err = AgentError::CapacityWait {
    kind: "claude".to_string(),
    wake_at: Utc::now(),
};
assert!(err.to_string().contains("waiting for claude capacity"));

Fields

kind: String

Provider kind the step needs (e.g. "claude").

wake_at: DateTime<Utc>

Moment the engine should wake the run and retry the step.

AccountNotFound

The step asked for a provider account by name and none matches.

Never falls back to another account or to the worker’s own token: a step pinned to an account must not silently spend another one.

Examples

use ironflow_core::error::AgentError;

let err = AgentError::AccountNotFound {
    name: "team-a".to_string(),
};
assert_eq!(err.to_string(), "provider account 'team-a' not found");

Fields

name: String

The account name the step asked for.

Trait Implementations

impl Debug for AgentError

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

Formats the value using the given formatter.

impl Display for AgentError

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

Formats the value using the given formatter.

impl Error for AgentError

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<AgentError> for OperationError

fn from(source: AgentError) -> Self

Converts to this type from the input type.