Enum CompletionError 

#[non_exhaustive]
pub enum CompletionError {
    HttpError(Error),
    JsonError(Error),
    UrlError(ParseError),
    RequestError(Box<dyn Error + Send + Sync + 'static>),
    ResponseError(String),
    ProviderError(String),
    ProviderResponse(ProviderResponseError),
}

Errors returned by completion models.

Inspect provider failures with Self::provider_response_body, Self::provider_response_json, and Self::provider_response_status. These recover the provider’s raw HTTP status and response body so you can branch on a provider error code or surface a precise diagnostic. The same helpers are available on EmbeddingError, ImageGenerationError, AudioGenerationError, TranscriptionError, RerankError, and (forwarded) PromptError.

use rig_core::completion::CompletionError;

/// Log the provider's raw error response when a completion fails.
fn report(error: &CompletionError) {
    if let Some(status) = error.provider_response_status() {
        // Note: this can be a 2xx status for providers that return an error
        // envelope alongside a success status — the error itself means failure.
        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 (e.g. a transport error)"),
        Err(_) => eprintln!(
            "provider response body was not valid JSON: {:?}",
            error.provider_response_body(),
        ),
    }
}

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.

HttpError(Error)

Http error (e.g.: connection error, timeout, etc.)

JsonError(Error)

Json error (e.g.: serialization, deserialization)

UrlError(ParseError)

Url error (e.g.: invalid URL)

RequestError(Box<dyn Error + Send + Sync + 'static>)

Available on non-target_family=wasm only.

Error building the completion request

ResponseError(String)

Error parsing the completion response

ProviderError(String)

Error returned by the completion model provider

ProviderResponse(ProviderResponseError)

Raw error response preserved from the completion model provider

Implementations

impl CompletionError

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

Builds an error from a captured HTTP status and raw response body, routing it so the provider_response_* helpers stay useful.

This is the single funnel every HTTP-error path should use instead of flattening a status and body into a ProviderError(String):

• A success (2xx) status carries a provider-authored error envelope, so it is preserved as Self::ProviderResponse together with the status.
• A non-success status is preserved as Self::HttpError(http_client::Error::InvalidStatusCodeWithMessage).

Either way the raw body is kept verbatim and the status stays recoverable through Self::provider_response_status. Read the response body exactly once and hand it here for both branches.

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

Preserves a raw provider error body that has no HTTP status.

Use this for non-HTTP transports (gRPC / SDK clients such as AWS Bedrock, Vertex AI, or the gRPC Gemini client) where the provider returns an error payload but no http::StatusCode is available. The body is preserved as Self::ProviderResponse with status == None, so Self::provider_response_body still surfaces it while Self::provider_response_status returns None.

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

Returns the raw provider response body when available.

This is available for:

• Self::ProviderResponse using its preserved body.
• Self::HttpError when it wraps an HTTP non-success response that carries a body.

Returns None for any other variant — for example a Rig-generated ProviderError diagnostic, or a failure from a transport with no provider response body to preserve. An empty preserved body is reported as Some("") (the provider returned no payload), which is distinct from None; note that Self::provider_response_json maps that same empty body to Ok(None).

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

Parses the provider response body as JSON.

Returns:

• Ok(Some(value)) when a body is present and valid JSON.
• Ok(None) when no provider response body is available.
• Err(error) when a body is present but isn’t valid JSON.

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

Returns the HTTP status code when this error preserves one, either from a non-success HTTP response, from a preserved provider response, or from a 2xx error envelope.

Warning: this can return a 2xx status. Some providers send an error envelope alongside a success status, which Rig preserves via Self::ProviderResponse. Callers must not infer failure from the status code alone — the existence of this error already means the call failed. Returns None for non-HTTP transports (gRPC / SDK clients) and for variants that carry no provider response.

Trait Implementations

impl Debug for CompletionError

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

Formats the value using the given formatter.

impl Display for CompletionError

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

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.

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

fn from(source: Box<dyn Error + Send + Sync + 'static>) -> Self

Converts to this type from the input type.

impl From<CompletionError> for StreamingError

fn from(source: CompletionError) -> Self

Converts to this type from the input type.

impl From<CompletionError> for PromptError

fn from(source: CompletionError) -> Self

Converts to this type from the input type.

impl From<CompletionError> for ExtractionError

fn from(source: CompletionError) -> Self

Converts to this type from the input type.

impl From<Error> for CompletionError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for CompletionError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<MessageError> for CompletionError

fn from(error: MessageError) -> Self

Converts to this type from the input type.

impl From<ParseError> for CompletionError

fn from(source: ParseError) -> Self

Converts to this type from the input type.