Enum LlmError 

#[non_exhaustive]
pub enum LlmError {
    UnsupportedProvider {
        provider: String,
    },
    ConfigurationError {
        message: String,
    },
    RequestFailed {
        message: String,
        source: Option<Box<dyn Error + Send + Sync>>,
    },
    ResponseParsingError {
        message: String,
    },
    RateLimitExceeded {
        retry_after_seconds: u64,
    },
    Timeout {
        timeout_seconds: u64,
    },
    AuthenticationFailed {
        message: String,
    },
    TokenLimitExceeded {
        current: usize,
        max: usize,
    },
    ToolExecutionFailed {
        tool_name: String,
        message: String,
    },
    SchemaValidationFailed {
        message: String,
    },
}

Errors that can occur during LLM operations.

This enum covers all error conditions you might encounter when using multi-llm. Each variant includes relevant context and can be:

• Categorized via category()
• Assessed for severity via severity()
• Checked for retryability via is_retryable()
• Converted to user-friendly messages via user_message()

Creating Errors

Use the constructor methods which automatically log the error:

use multi_llm::LlmError;

// These methods log automatically
let err = LlmError::configuration_error("Missing API key");
let err = LlmError::rate_limit_exceeded(60);
let err = LlmError::timeout(30);

Error Categories

Variant	Category	Retryable
UnsupportedProvider	Client	No
ConfigurationError	Client	No
RequestFailed	External	Yes
ResponseParsingError	External	No
RateLimitExceeded	Transient	Yes
Timeout	Transient	Yes
AuthenticationFailed	Client	No
TokenLimitExceeded	Client	No
ToolExecutionFailed	External	No
SchemaValidationFailed	Client	No

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.

UnsupportedProvider

The specified provider is not supported.

Supported providers: “anthropic”, “openai”, “ollama”, “lmstudio”

Fields

provider: String

The provider name that was requested.

ConfigurationError

Provider configuration is invalid or incomplete.

Common causes:

• Missing API key for providers that require one
• Invalid base URL format
• Incompatible configuration values

Fields

message: String

Description of the configuration problem.

RequestFailed

The HTTP request to the provider failed.

This is a general failure that may be retryable. Check the source error for more details about the underlying cause.

Fields

message: String

Description of the failure.

source: Option<Box<dyn Error + Send + Sync>>

The underlying error, if available.

ResponseParsingError

Failed to parse the provider’s response.

The provider returned a response, but it couldn’t be parsed. This might indicate a provider API change or malformed response.

Fields

message: String

Details about the parsing failure.

RateLimitExceeded

Provider rate limit exceeded.

The provider is throttling requests. Wait the indicated time before retrying. Consider implementing exponential backoff.

Fields

retry_after_seconds: u64

Recommended wait time before retrying.

Timeout

Request timed out.

The provider didn’t respond within the configured timeout. This is usually retryable but may indicate an overloaded provider.

Fields

timeout_seconds: u64

The timeout duration that was exceeded.

AuthenticationFailed

Authentication with the provider failed.

Check your API key or credentials. This is not retryable without fixing the authentication.

Fields

message: String

Details about the authentication failure.

TokenLimitExceeded

Request exceeds the model’s token limit.

The combined input (messages + tools) is too large for the model’s context window. Reduce the input size or use a model with larger context.

Fields

current: usize

The actual token count of the request.

max: usize

The maximum allowed tokens for the model.

ToolExecutionFailed

A tool execution failed.

The tool was called but couldn’t complete successfully. Check the message for details about why the tool failed.

Fields

tool_name: String

The name of the tool that failed.

message: String

Details about the failure.

SchemaValidationFailed

Response doesn’t match the requested JSON schema.

When using structured output, the model’s response didn’t conform to the provided JSON schema. May require a clearer prompt or different schema design.

Fields

message: String

Details about the validation failure.

Implementations

impl LlmError

pub fn category(&self) -> ErrorCategory

Get the error category for routing and handling decisions.

Use this to determine how to handle different types of errors:

• Client: Fix the request (invalid input, auth, config)
• External: Provider issue, may need ops attention
• Transient: Retry with backoff

Example

use multi_llm::{LlmError, error::ErrorCategory};

fn handle(err: LlmError) {
    match err.category() {
        ErrorCategory::Transient => {
            // Implement retry logic
        }
        ErrorCategory::Client => {
            // User can fix this, show helpful message
        }
        _ => {
            // Log for investigation
        }
    }
}

pub fn severity(&self) -> ErrorSeverity

Get the error severity for logging and alerting.

Use this to determine logging level and whether to alert on-call.

pub fn is_retryable(&self) -> bool

Whether this error is transient and should trigger a retry.

Returns true for:

• Rate limit exceeded
• Timeouts
• General request failures (may be network issues)

Implement exponential backoff when retrying these errors.

pub fn user_message(&self) -> String

Convert to a user-friendly message suitable for display.

Returns a message that’s safe to show to end users - technical details and internal information are stripped or generalized.

Example

use multi_llm::LlmError;

let err = LlmError::rate_limit_exceeded(60);
let msg = err.user_message();
// "Service is busy. Please wait 60 seconds and try again"

pub fn unsupported_provider(provider: impl Into<String>) -> Self

Create an unsupported provider error (logs at ERROR level).

pub fn configuration_error(message: impl Into<String>) -> Self

pub fn request_failed( message: impl Into<String>, source: Option<Box<dyn Error + Send + Sync>>, ) -> Self

pub fn response_parsing_error(message: impl Into<String>) -> Self

pub fn rate_limit_exceeded(retry_after_seconds: u64) -> Self

pub fn timeout(timeout_seconds: u64) -> Self

pub fn authentication_failed(message: impl Into<String>) -> Self

pub fn token_limit_exceeded(current: usize, max: usize) -> Self

pub fn tool_execution_failed( tool_name: impl Into<String>, message: impl Into<String>, ) -> Self

pub fn schema_validation_failed(message: impl Into<String>) -> Self

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.