Enum LlmError 

#[non_exhaustive]
pub enum LlmError {
    Http(Error),
    Json(Error),
    Io(Error),
    RateLimited,
    Unavailable,
    EmptyResponse {
        provider: String,
    },
    SseParse(String),
    EmbedUnsupported {
        provider: String,
    },
    ModelLoad(String),
    Inference(String),
    NoRoute,
    NoProviders,
    StructuredParse(String),
    TranscriptionFailed(String),
    ContextLengthExceeded,
    Timeout,
    BetaHeaderRejected {
        header: String,
    },
    InvalidInput {
        provider: String,
        message: String,
    },
    ApiError {
        provider: String,
        status: u16,
    },
    Other(String),
}

Errors that can occur in any crate::provider::LlmProvider operation.

Use the predicate methods (is_rate_limited, is_context_length_error, is_invalid_input, is_beta_header_rejected) to classify errors before deciding whether to retry, fall back, or propagate.

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.

Http(Error)

Underlying HTTP transport error (connection refused, TLS failure, etc.).

Json(Error)

The API returned a response that could not be decoded as valid JSON.

Io(Error)

An I/O error occurred (e.g. reading or writing a cache file).

RateLimited

The provider returned HTTP 429 (too many requests). Callers should back off and retry.

Unavailable

The provider is temporarily unavailable (HTTP 5xx or connection error).

EmptyResponse

The provider returned a successful HTTP status but no content in the response body.

Fields

provider: String

SseParse(String)

A Server-Sent Events frame could not be parsed.

EmbedUnsupported

crate::provider::LlmProvider::embed was called on a provider that does not support embedding generation.

Fields

provider: String

ModelLoad(String)

Candle model weights or tokenizer could not be loaded from disk or HuggingFace Hub.

Inference(String)

The Candle inference worker returned an error or timed out.

NoRoute

The crate::router::RouterProvider has no providers configured.

NoProviders

All providers in a router have been exhausted without a successful response.

StructuredParse(String)

crate::provider::LlmProvider::chat_typed could not parse the model’s response as the requested type, even after a retry.

TranscriptionFailed(String)

The speech-to-text backend rejected the audio or returned an error.

ContextLengthExceeded

The prompt exceeds the model’s maximum context window. Do not retry with the same input on another provider — the same input will fail there too. Summarize or truncate first.

Timeout

The request exceeded the configured per-call timeout.

BetaHeaderRejected

A beta header sent in the request was rejected by the API (e.g. compact-2026-01-12 deprecated or not yet available). The provider has already disabled the feature internally; the caller should retry without it.

Fields

header: String

InvalidInput

The input itself is invalid (HTTP 400). Retrying with the same input on another provider will not help — the router should break the fallback loop immediately.

Fields

provider: String

message: String

ApiError

A provider returned a non-success HTTP status that does not map to any more specific variant.

This covers non-retriable API failures such as authentication errors (401/403), server errors (500/503), and unexpected 4xx responses that are not InvalidInput, RateLimited, or ContextLengthExceeded. Callers should not retry on this error.

Fields

provider: String

status: u16

Other(String)

Catch-all for provider-specific errors that do not yet have a typed variant.

Deprecation

Prefer adding a typed variant or propagating a specific source error. This variant exists for backward compatibility and will be removed once all callsites are migrated.

Implementations

impl LlmError

pub fn is_context_length_error(&self) -> bool

Returns true if this error indicates the context/prompt is too long for the model.

Providers must return LlmError::ContextLengthExceeded directly; this predicate does not inspect error message strings.

pub fn is_beta_header_rejected(&self) -> bool

Returns true if this error indicates that a beta header was rejected by the API.

pub fn is_invalid_input(&self) -> bool

Returns true if this error indicates that the input itself is invalid (HTTP 400).

Callers (e.g. the router fallback loop) should not retry with a different provider when this is true — the same input will fail there too.

pub fn is_rate_limited(&self) -> bool

Trait Implementations

impl Debug for LlmError

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

Formats the value using the given formatter.

impl Display for LlmError

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

Formats the value using the given formatter.

impl Error for LlmError

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 LlmError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for LlmError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for LlmError

fn from(source: Error) -> Self

Converts to this type from the input type.