Enum CompletionError 

pub enum CompletionError {
    HttpError(Error),
    JsonError(Error),
    UrlError(ParseError),
    RequestError(Box<dyn Error + Send + Sync>),
    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, and RerankError.

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

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>)

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>, ) -> CompletionError

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_http_response_with_request_id( status: StatusCode, body: impl Into<String>, provider_request_id: Option<String>, ) -> CompletionError

Self::from_http_response for paths that captured the provider’s transport request id alongside the response (rig#2314).

Unlike the metadata-less funnel, a non-success status is preserved as Self::ProviderResponse too — http_client’s error type has no slot for provider metadata, and the id the provider reported on a failed call is exactly what support asks for. Classification therefore follows the code path (did this call site capture transport metadata?), never the presence of the header on a particular response, so a given provider’s errors classify consistently. The status stays recoverable through Self::provider_response_status and the id through Self::provider_request_id.

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

Attaches the response’s headers to an error just built by one of the from_http_response* funnels, so rate-limit metadata (Retry-After, x-ratelimit-*) survives onto it (rig#2210).

This is a separate step rather than a funnel parameter because the funnels’ classification is fixed by the call path (does this provider have a request-id contract?), while header capture depends only on whether the transport handed the response back. Both routes can therefore carry headers: Self::ProviderResponse stores them alongside the request id, and a non-success Self::HttpError is upgraded in place to http_client::Error::InvalidStatusCodeWithDetails, which displays identically to the header-less variant.

Passing None leaves the error untouched, as does calling this on a variant with no response to annotate. An error that already captured headers keeps the ones it has: the first capture is the one that saw the response, so this never overwrites.

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

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.

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

Returns the provider’s transport request id for the failed call, when the capture path preserved one (rig#2314) — the id provider support asks for. None for providers that report none, for paths that captured no transport metadata, and for errors with no provider response at all.

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

Returns the response’s headers when the capture path preserved them (rig#2210) — the rate-limit metadata (Retry-After, x-ratelimit-*) a caller needs to back off correctly:

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

Returns None when no headers were captured: non-HTTP transports (gRPC / SDK clients), Rig-generated diagnostics, errors funnelled from only a status and body (e.g. via Self::from_http_response), and transports that report a non-success status without preserving them. None therefore means “not captured”, never “the response had no headers”.

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, __formatter: &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.

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

fn from(source: Box<dyn Error + Send + Sync>) -> CompletionError

Converts to this type from the input type.

impl From<CompletionError> for ConformanceError

fn from(source: CompletionError) -> ConformanceError

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<CompletionError> for ScenarioError

Available on crate feature test-utils only.

fn from(source: CompletionError) -> Self

Converts to this type from the input type.

impl From<Error> for CompletionError

fn from(source: Error) -> CompletionError

Converts to this type from the input type.

impl From<Error> for CompletionError

fn from(source: Error) -> CompletionError

Converts to this type from the input type.

impl From<MessageError> for CompletionError

fn from(error: MessageError) -> CompletionError

Converts to this type from the input type.

impl From<ParseError> for CompletionError

fn from(source: ParseError) -> CompletionError

Converts to this type from the input type.