Enum FailureReason 

pub enum FailureReason {
    Truncated,
    ContentFiltered,
    InvalidOutput,
    RateLimited,
    RequestRejected,
    ProviderUnavailable,
    Transport,
    Cancelled,
    Incomplete,
}

Why one element of a dispatch is not a clean completion.

Per-element, and orthogonal to LlmCallError: the request did reach the model. Several of these still carry usable text on the LlmOutcome — a truncated or content-filtered completion is ok: false and has a partial answer worth reading.

A closed set of nine. It is what a guest branches on, so a provider that meets something it cannot place reports Self::Incomplete and puts the raw provider spelling in LlmFailure::finish_reason rather than widening this.

Variants

Truncated

Hit the output-token ceiling mid-answer (finishReason of length). The partial text is retained — that is the whole reason the failure arm has a text field.

ContentFiltered

The provider’s safety filter stopped or redacted the completion. Reached from both directions: generateText resolves with a filtered result while generateObject throws on the same input, and both normalize to here.

InvalidOutput

The provider answered, but not with something usable: malformed output, or output that ignored the requested schema. Distinct from Self::Truncated — nothing was cut off, what arrived was wrong.

RateLimited

The provider throttled this element (structurally, a 429). Honor any reported retry-after before re-dispatching.

RequestRejected

The provider refused the request itself rather than failing to answer it: a rejected credential, a malformed or oversized request, or a prompt that does not fit the model’s context window. These share an arm because they share a shape — the request as sent will never succeed, so retrying it unchanged cannot help.

ProviderUnavailable

The provider was reachable but could not serve the request (structurally, a 5xx). Unlike Self::RequestRejected the request itself may be fine, so the same bytes may succeed later.

Transport

The connection failed for this element after dispatch had begun — no HTTP status was ever observed. Sibling elements may still have succeeded.

Cancelled

The element was abandoned before the model finished — deadline, shutdown, or an aborted request. Classified separately from Self::Transport because the cause is on this side, not the wire.

Incomplete

The provider stopped for a reason this runtime does not classify. The raw provider spelling travels in LlmFailure::finish_reason for diagnosis.

Implementations

impl FailureReason

pub const ALL: [FailureReason; 9]

Every reason, in the plan’s declaration order. Kept so a mapper or a guest-facing enumeration cannot silently omit one.

pub fn as_str(&self) -> &'static str

The stable kebab-case spelling. This is the wire form: it is what any guest-facing rendering uses, so it must not drift.

pub fn default_message(&self) -> &'static str

A fixed classification string for this reason, suitable as an LlmFailure::message when a provider has nothing more specific that is safe to say. Drawn from a closed vocabulary precisely so it cannot carry a response body or completion fragment.

pub fn retryable_by_default(&self) -> bool

Whether re-dispatching the identical request could plausibly succeed.

The default a provider starts from, not the last word: it may override per element (see LlmFailure::retryable) when it knows better — a 429 carrying a retry-after is retryable, while one on an exhausted quota is not.

Trait Implementations

impl Clone for FailureReason

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for FailureReason

impl Debug for FailureReason

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

Formats the value using the given formatter.

impl Display for FailureReason

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

Formats the value using the given formatter.

impl Eq for FailureReason

impl PartialEq for FailureReason

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for FailureReason