Enum Error 

pub enum Error {
    Http(Error),
    Json(Error),
    Api {
        status: u16,
        message: String,
    },
    Agent(String),
    Auth(String),
    MaxTurnsExceeded(usize),
    Truncated,
    RunTimeout(Duration),
    Mcp(String),
    A2a(String),
    Config(String),
    Store(String),
    Memory(String),
    Knowledge(String),
    Guardrail(String),
    Daemon(String),
    Sensor(String),
    BudgetExceeded {
        used: u64,
        limit: u64,
    },
    Channel(String),
    Telegram(String),
    KillSwitch(String),
    Sandbox(String),
    TenantOverloaded {
        tenant_id: String,
        in_flight: usize,
        cap: usize,
    },
    CircuitOpen {
        until: Instant,
        prev_duration: Duration,
    },
    WithPartialUsage {
        source: Box<Error>,
        usage: TokenUsage,
    },
}

Top-level error type for the heartbit-core crate.

All fallible public APIs return Result<T, Error>. Callers should match on specific variants rather than converting to strings so that retry logic and error reporting remain precise.

Retryable variants

The following variants indicate transient conditions that callers may retry:

• Error::Http — network-level failures (connection reset, timeout, …)
• Error::Api with status >= 500 or status == 429
• Error::TenantOverloaded — back off and retry when capacity is available
• Error::CircuitOpen — retry after the until instant

Token accounting

Error::WithPartialUsage wraps any other variant and carries the token usage accumulated before the failure. Inspect it with Error::partial_usage to charge tokens even on error.

Variants

Http(Error)

An HTTP-level error from the reqwest client (network failure, TLS error, etc.).

Potentially retryable depending on the underlying cause.

Json(Error)

JSON serialization or deserialization failed.

Indicates a protocol mismatch or a malformed API response. Not retryable.

Api

The LLM API returned a non-2xx HTTP status code.

status == 429 is rate-limited (retryable). status >= 500 is a server error (retryable). status == 400 / 401 / 403 are not retryable without changing the request.

Fields

status: u16

HTTP status code returned by the API.

message: String

Human-readable error message from the response body.

Agent(String)

A general agent-level error not covered by a more specific variant.

Produced by tool execution failures, orchestrator logic errors, and other agent-layer problems.

Auth(String)

Authentication or authorization failure.

Typically indicates a missing or invalid API key. Not retryable without supplying valid credentials.

MaxTurnsExceeded(usize)

The agent loop reached its configured maximum turn count without finishing.

Not retryable — callers should increase max_turns or redesign the task.

Truncated

The LLM response was cut off because max_tokens was reached.

The agent loop surfaces this as an error when truncation is fatal. Callers can increase max_tokens or compress context and retry.

RunTimeout(Duration)

The agent run exceeded the configured wall-clock timeout.

Potentially retryable with a longer timeout or a simpler task.

Mcp(String)

An error originating from the Model Context Protocol (MCP) client or server.

Covers handshake failures, protocol violations, and tool call errors returned by remote MCP servers.

A2a(String)

An error from the Agent-to-Agent (A2A) protocol layer.

Returned when communicating with remote A2A agents fails.

Config(String)

An error in configuration parsing or validation.

Produced by HeartbitConfig deserialization and by builder build() calls that detect invalid combinations of options.

Store(String)

A persistence-layer error (e.g., PostgreSQL task-store failure).

Potentially retryable on transient connection errors.

Memory(String)

An error in the agent memory subsystem (recall, store, prune, etc.).

Knowledge(String)

An error in the knowledge-base subsystem (indexing, chunking, search).

Guardrail(String)

A guardrail denied or errored during a request.

Produced when a crate::Guardrail hook returns Deny or when the guardrail itself fails. The message contains the denial reason.

Daemon(String)

An error in the daemon execution path (Kafka consumer, dispatcher, etc.).

Sensor(String)

An error in the sensor pipeline (RSS, webhook, schedule triggers).

BudgetExceeded

The agent exceeded its token budget before completing.

used is the total tokens consumed; limit is the configured cap. Not retryable without either increasing the budget or reducing the task.

Fields

used: u64

Total tokens consumed before the budget was exhausted.

limit: u64

The configured token budget that was exceeded.

Channel(String)

An error in the WebSocket/session channel layer.

Telegram(String)

An error originating from the Telegram bot adapter.

KillSwitch(String)

A kill switch was activated, terminating the agent run immediately.

Produced by the kill-switch guardrail when a prohibited pattern is detected.

Sandbox(String)

The agent attempted a filesystem operation that violates the sandbox policy.

Produced by CorePathPolicy::check_path or the Landlock sandbox.

TenantOverloaded

The tenant has reached its maximum concurrent-request capacity.

Retryable: callers should back off and retry after a delay.

Fields

tenant_id: String

The tenant identifier that is overloaded.

in_flight: usize

Number of requests currently in flight for this tenant.

cap: usize

Maximum allowed concurrent requests for this tenant.

CircuitOpen

The LLM provider’s circuit breaker is open; requests are being shed.

Retryable: callers should retry after the until instant has passed.

Fields

until: Instant

The instant after which requests should be retried.

prev_duration: Duration

How long the circuit was open in the previous open window.

WithPartialUsage

Wraps another error with partial token usage accumulated before failure.

Used by AgentRunner::execute to surface tokens consumed before an error. Inspect partial usage with Error::partial_usage. Re-wrapping an existing WithPartialUsage replaces the usage rather than nesting.

Fields

source: Box<Error>

The underlying error that caused the agent run to abort.

usage: TokenUsage

Token usage accumulated before the error occurred.

Implementations

impl Error

pub fn with_partial_usage(self, usage: TokenUsage) -> Self

Wrap this error with partial token usage data.

If self is already WithPartialUsage, the inner error is unwrapped first to prevent nesting. The new usage replaces the old one.

pub fn accumulate_usage(self, prior: TokenUsage) -> Self

Wrap this error with the sum of prior usage and the error’s own partial usage.

Shorthand for e.with_partial_usage(prior + e.partial_usage()).

pub fn partial_usage(&self) -> TokenUsage

Extract partial token usage from this error. Returns TokenUsage::default() for errors that don’t carry usage data.

Trait Implementations

impl Debug for Error

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

Formats the value using the given formatter.

impl Display for Error

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

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) -> Self

Converts to this type from the input type.

impl From<Error> for Error

fn from(source: Error) -> Self

Converts to this type from the input type.