Struct LlmFailure 

pub struct LlmFailure {
    pub reason: FailureReason,
    pub message: String,
    pub retryable: bool,
    pub status: Option<u16>,
    pub finish_reason: Option<String>,
    pub local: bool,
}

The failure-arm payload of an LlmOutcome: everything that exists only when ok is false.

Held in an Option on the outcome rather than flattened into it, so the success arm cannot carry a message, a retryable, or a status — those fields are meaningless on a clean completion, and a flattened struct would have to invent values for them.

Fields

reason: FailureReason

The closed-set classification a guest branches on.

message: String

The degraded error string.

This is the AI SDK’s rule that an error: unknown becomes an errorText: string at any serialization boundary — a guest cannot receive a Rust error object, so it receives this. The no-payload rule binds it absolutely: it is a classification, never an echo. No prompt, no completion fragment, and no provider response body may reach it; provider bodies carry request echoes and account identifiers, so they are dropped at this boundary. FailureReason::default_message supplies a safe one.

retryable: bool

Whether re-dispatching the identical request could plausibly succeed. Defaulted from FailureReason::retryable_by_default and overridable per element, because a provider sometimes knows more than the class does.

status: Option<u16>

The HTTP status, when one was observed. None is meaningful rather than missing: a transport death never got a status, which is exactly what distinguishes it from a provider that answered with an error.

finish_reason: Option<String>

The provider’s own raw stop reason, verbatim, for diagnosis only.

Deliberately separate from Self::reason. reason is the closed set a guest branches on; this is an open string that varies per provider and per SDK version. Folding them together would either force the closed set to grow with every provider quirk or silently discard the detail that makes an unclassified stop diagnosable.

local: bool

Refused by this host’s own configuration or network policy before the provider was reached, rather than answered by it. Not part of what a guest sees: the call log records such a failure as kind local, so a replay does not serve it.

Implementations

impl LlmFailure

pub fn new(reason: FailureReason, message: impl Into<String>) -> Self

A failure of this class carrying this classification message. retryable starts from the reason’s default; status and finish_reason start absent.

pub fn retryable(self, retryable: bool) -> Self

Override the class default when the provider knows better.

pub fn with_status(self, status: u16) -> Self

Record the observed HTTP status. Left absent when none was seen.

pub fn refused_locally(self) -> Self

Mark the failure as this host’s own refusal; see Self::local.

pub fn with_finish_reason(self, finish_reason: impl Into<String>) -> Self

Record the provider’s raw stop reason for diagnosis.

Trait Implementations

impl Clone for LlmFailure

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for LlmFailure

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

Formats the value using the given formatter.

impl Eq for LlmFailure

impl PartialEq for LlmFailure

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for LlmFailure