Enum ProviderError 

pub enum ProviderError {
    Http(Arc<Error>),
    Json(Arc<Error>),
    Url(ParseError),
    Request(SharedError),
    Response(String),
    Provider(String),
    ProviderResponse(ProviderResponseError),
    InvalidAuthentication(ProviderResponseError),
    CacheExpired {
        name: String,
        response: ProviderResponseError,
    },
    MismatchedDimensions {
        provider: String,
        requested: usize,
        returned: usize,
    },
    MalformedToolInput(MalformedToolInput),
    Relayed(Box<ErrorReport>),
    Truncated,
    DuplicateCallId(CallId),
}

A failed provider operation: completion, embedding, reranking, transcription, image or audio generation, verification, model listing, or context caching.

The variant is the classification, and each variant maps to one ErrorKind. A provider’s reply is preserved as a ProviderResponseError with its status, body, headers, and request ID; read it through Self::provider_response or the accessors below.

use rig_core::error::ProviderError;

fn log(error: &ProviderError) {
    if let Some(status) = error.provider_response_status() {
        // Error envelopes can arrive with successful HTTP statuses.
        eprintln!("provider returned HTTP {status}");
    }
    match error.provider_response_json() {
        Ok(Some(json)) => eprintln!("provider error payload: {json}"),
        Ok(None) => eprintln!("no provider response body: {error}"),
        Err(_) => eprintln!("non-JSON body: {:?}", error.provider_response_body()),
    }
}

Errors are Clone: sources are shared, so a stream that already yielded an error can hand the same error to a later caller.

Variants

Http(Arc<Error>)

A transport failure that produced no provider reply: a reset connection, a timeout, an unreadable response. A reply the server made is Self::ProviderResponse.

Json(Arc<Error>)

JSON serialization or deserialization failed.

Url(ParseError)

A URL could not be parsed.

Request(SharedError)

The request could not be built.

Response(String)

The reply decoded but does not answer the request.

Provider(String)

The provider reported a failure without a preserved reply.

ProviderResponse(ProviderResponseError)

The provider’s reply, preserved: a non-success status with its body, a 2xx error envelope, or a non-HTTP transport’s error payload.

InvalidAuthentication(ProviderResponseError)

The provider rejected the configured credentials with 401 or 403.

CacheExpired

A request for an existing context-cache handle answered 403 or 404. The reply’s body is the provider’s explanation, which can name a cause other than expiry, such as a credential or quota failure.

Fields

name: String

The cache handle the request named.

response: ProviderResponseError

The provider’s reply.

MismatchedDimensions

The provider returned vectors of a width other than the one the caller declared through an embedding wire’s ndims argument. Raised only when the width was set explicitly.

Fields

provider: String

Provider whose response disagreed with the declared width.

requested: usize

Width the caller declared.

returned: usize

Width the provider actually returned.

MalformedToolInput(MalformedToolInput)

A tool block the provider declared complete carried input that is not valid JSON. Its report carries the input as ErrorDetail::MalformedToolInput.

Relayed(Box<ErrorReport>)

A failure a relay delivered as its report, such as a stream relayed over the effect bus. It reports as the relayed report, unchanged.

Truncated

The reply stopped before the provider ended it: its frames ran out, or the runtime stopped, without the provider’s end.

DuplicateCallId(CallId)

The provider named two tool calls of one reply with the same id.

Implementations

impl ProviderError

pub fn request(reason: impl Into<BoxError>) -> Self

A request that could not be built, for the given reason.

pub fn from_http_response(status: StatusCode, body: impl Into<String>) -> Self

Preserves the status and verbatim body as Self::ProviderResponse, including error envelopes returned with 2xx statuses.

pub fn from_provider_body(body: impl Into<String>) -> Self

Preserves a verbatim provider error body with no HTTP status as Self::ProviderResponse.

pub fn from_transport_error(error: Error) -> Self

Converts a non-success reply the transport reported as an error to Self::ProviderResponse, keeping its status, body, and headers. Other transport errors become Self::Http.

pub fn kind(&self) -> ErrorKind

The classification this error reports as.

pub fn is_retryable(&self) -> bool

Classifies transport failures with transient_transport and preserved replies with ProviderResponseError::is_retryable; a truncated reply is retryable. Every other failure, rejected credentials and expired caches included, is not retryable.

pub fn provider_response(&self) -> Option<&ProviderResponseError>

The provider’s preserved reply, when this error carries one.

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

The preserved reply’s body. An empty body returns Some(""), while Self::provider_response_json maps it to Ok(None).

pub fn provider_response_json(&self) -> Result<Option<Value>, Error>

Parses the preserved reply’s body as JSON: Ok(None) when there is no body or it is empty, Err when it is not valid JSON.

pub fn provider_response_status(&self) -> Option<StatusCode>

The preserved reply’s HTTP status. It may be 2xx for an error envelope.

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

The provider’s transport request ID, when the reply carried one.

pub fn provider_response_headers(&self) -> Option<&HeaderMap>

The preserved reply’s headers. None means not captured, as for non-HTTP transports and replies built from only a status and body. This example reads the seconds form of Retry-After:

fn backoff(error: &ProviderError) -> Option<Duration> {
    let seconds = error
        .provider_response_headers()?
        .get(http::header::RETRY_AFTER)?
        .to_str()
        .ok()?
        .parse()
        .ok()?;
    Some(Duration::from_secs(seconds))
}

pub fn with_provider_request_id(self, request_id: Option<String>) -> Self

Fills an absent request ID on the preserved reply, ignoring empty strings.

pub fn with_response_headers(self, headers: Option<HeaderMap>) -> Self

Fills absent headers on the preserved reply.

pub fn with_provider_status(self, status: Option<StatusCode>) -> Self

Attaches the HTTP status a transport reported beside a reply preserved without one, so it classifies by status. A captured status is kept.

pub fn with_provider_code(self, code: Option<String>) -> Self

Attaches the provider’s machine-readable code for the failure, such as a gRPC status name or an AWS exception type.

pub fn with_transient(self, transient: Option<bool>) -> Self

Replaces the preserved reply’s transport retry verdict, used when its status is absent or successful.

pub fn report(&self) -> ErrorReport

The wire form of this error.

Trait Implementations

impl Clone for ProviderError

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 ProviderError

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

Formats the value using the given formatter.

impl Display for ProviderError

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

Formats the value using the given formatter.

impl Error for ProviderError

The source is the shared error itself, not its Arc, so callers can downcast it.

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<&ProviderError> for ErrorReport

fn from(error: &ProviderError) -> Self

Converts to this type from the input type.

impl From<Box<dyn Error + Send + Sync>> for ProviderError

fn from(error: BoxError) -> Self

Converts to this type from the input type.

impl From<EncodeError> for ProviderError

fn from(error: EncodeError) -> Self

Converts to this type from the input type.

impl From<Error> for ProviderError

fn from(error: Error) -> Self

Converts to this type from the input type.

impl From<Error> for ProviderError

fn from(error: Error) -> Self

Converts to this type from the input type.

impl From<Error> for ProviderError

fn from(error: Error) -> Self

Converts to this type from the input type.

impl From<MessageError> for ProviderError

fn from(error: MessageError) -> Self

Converts to this type from the input type.

impl From<ParseError> for ProviderError

fn from(error: ParseError) -> Self

Converts to this type from the input type.

impl From<ProviderError> for ErrorReport

fn from(error: ProviderError) -> Self

Converts to this type from the input type.

impl From<ProviderError> for ConformanceError

Available on crate feature test-utils only.

fn from(source: ProviderError) -> Self

Converts to this type from the input type.

impl From<ProviderError> for VectorStoreError

fn from(source: ProviderError) -> Self

Converts to this type from the input type.