Struct CompletionError 

#[non_exhaustive]
pub struct CompletionError { /* private fields */ }

The error a model round or a catalog fetch fails with.

The caller that performs the round or fetch reports this error. For a model round, it comes back into the Engine in a Chat effect’s answer.

It holds a kind from a closed set, a message written for the operator and the model, and optional extras: the token counts of a context overflow, the backend’s finish_reason for an empty reply, a provider detail, and the underlying cause behind std::error::Error::source. Display shows only the message. The detail is provider text that the caller bounded and control-escaped. It is an opt-in channel and never appears in Display.

The caller builds one with new or context_overflow and adds the extras with the with_ methods.

The message is the kind’s fixed phrase. For a failure that came from an HTTP status, the caller appends (status N). A 401 or 403 is Unavailable, and its message uses the phrase the model backend did not accept the credentials. MalformedResponse, EmptyReply, and Unavailable may extend the message with : and specific text that the caller’s own code wrote, such as the byte limit that was hit. Provider text never enters the message. It goes in the detail.

Implementations

impl CompletionError

pub fn new( kind: CompletionErrorKind, message: impl Into<String>, ) -> CompletionError

Builds a failure of kind with message as its display text.

The caller uses the kind’s fixed phrase as the message. For a failure that came from an HTTP status, it appends (status N). A 401 or 403 is Unavailable, and its message uses the phrase the model backend did not accept the credentials. For MalformedResponse, EmptyReply, and Unavailable, the caller may extend the phrase with : and specific text that its own code wrote. Provider text never enters the message. The caller passes it to with_detail.

pub fn context_overflow( prompt_tokens: Option<u32>, window: Option<u32>, message: impl Into<String>, ) -> CompletionError

Builds a ContextOverflow failure with the token counts the provider stated. Pass None for a count the provider omitted.

pub fn with_source( self, source: impl Into<Box<dyn Error + Send + Sync>>, ) -> CompletionError

Keeps source as the underlying cause, reachable through std::error::Error::source.

pub fn with_finish_reason(self, reason: impl Into<String>) -> CompletionError

Records the finish_reason the backend gave, for an EmptyReply failure.

pub fn with_detail(self, text: impl Into<String>) -> CompletionError

Records provider text that explains the failure. The caller bounds and control-escapes the text before passing it. The text never appears in Display.

pub fn kind(&self) -> CompletionErrorKind

Returns the kind of this failure.

pub fn is_retryable(&self) -> bool

Returns true when retrying may succeed. The answer depends only on the kind. RateLimited, Overloaded, Timeout, Transport, ServerError, and MalformedResponse are retryable, and the rest are permanent.

pub fn overflow(&self) -> (Option<u32>, Option<u32>)

Returns the token counts that a context overflow reported, as (prompt_tokens, window). A count is None when the provider omitted it, and both are None for every kind other than ContextOverflow.

pub fn finish_reason(&self) -> Option<&str>

Returns the backend’s finish_reason when the failure was an empty model reply and the backend supplied one.

The Engine’s tool loop reads this value. An empty reply with Some("stop") after at least one answered tool call, including a call whose tool failed, is the model’s clean exit. An empty reply with a missing or "length" reason stays a hard failure.

pub fn message(&self) -> &str

Returns the message Display shows.

pub fn detail(&self) -> Option<&str>

Returns the provider text behind the failure, which the caller bounded and control-escaped.

The detail is an explicit opt-in diagnostic channel. The text never appears in Display, so a hostile or sensitive payload cannot forge log lines or leak into an error message.

Trait Implementations

impl Debug for CompletionError

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

Formats the value using the given formatter.

impl Display for CompletionError

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

Formats the value using the given formatter.

impl Error for CompletionError

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.