Enum GenaiError 

#[non_exhaustive]
pub enum GenaiError {
    Http(Error),
    Parse(String),
    Json(Error),
    Utf8(Utf8Error),
    Api {
        status_code: u16,
        message: String,
        request_id: Option<String>,
        retry_after: Option<Duration>,
    },
    Internal(String),
    InvalidInput(String),
    MalformedResponse(String),
    Timeout(Duration),
    ClientBuild(String),
}

Defines errors that can occur when interacting with the GenAI API.

Example: Handling API Errors

match client.interaction().create().await {
    Err(GenaiError::Api { status_code: 429, request_id, .. }) => {
        tracing::warn!("Rate limited, request_id: {:?}", request_id);
        // Retry with backoff
    }
    Err(GenaiError::Api { status_code, message, request_id }) => {
        tracing::error!("API error {}: {} (request: {:?})", status_code, message, request_id);
    }
    // ...
}

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.

Http(Error)

Parse(String)

Json(Error)

Utf8(Utf8Error)

Api

API error with structured context for debugging and automated handling.

Contains the HTTP status code (for retry logic), error message, and optional request ID (for correlation with Google API logs/support).

Fields

status_code: u16

HTTP status code (e.g., 400, 429, 500)

message: String

Error message from the API response body

request_id: Option<String>

Request ID from x-goog-request-id header, if available

retry_after: Option<Duration>

Retry delay from Retry-After header (for 429 rate limit errors).

When present, this indicates how long to wait before retrying. The value is parsed from the Retry-After header, which can be:

• Seconds (e.g., “120” → 120 seconds)
• HTTP date (e.g., “Wed, 21 Oct 2015 07:28:00 GMT” → duration until then)

This field is typically only populated for 429 (Too Many Requests) errors.

Internal(String)

InvalidInput(String)

MalformedResponse(String)

API returned a successful response but with unexpected or invalid content.

This indicates the API response didn’t match the expected schema, possibly due to API evolution or an undocumented response format. Unlike InvalidInput (user’s fault), this represents an issue with the API response itself.

Timeout(Duration)

Request timed out after the specified duration.

This error is returned when a request exceeds the timeout configured via with_timeout(). The duration indicates how long the request was allowed to run before being cancelled.

ClientBuild(String)

Failed to build the HTTP client.

This typically only occurs in exceptional circumstances such as TLS backend initialization failures.

Implementations

impl GenaiError

pub fn is_retryable(&self) -> bool

Returns true if this error is likely transient and the request may succeed on retry.

This helper identifies errors that are typically recoverable:

• HTTP errors: Network issues, connection resets, TLS errors
• Rate limits (429): Temporary throttling, retry after backoff
• Server errors (5xx): Temporary server issues
• Timeouts: Request took too long but may succeed with retry

Errors that return false are typically permanent and retrying won’t help:

• Client errors (4xx except 429): Bad request, unauthorized, not found
• Parse/JSON errors: Response format issues
• Invalid input: Request validation failures
• Malformed response: API contract violations

Example

use genai_rs::GenaiError;
use std::time::Duration;

fn should_retry(error: &GenaiError, attempt: u32, max_attempts: u32) -> bool {
    attempt < max_attempts && error.is_retryable()
}

// Rate limit errors are retryable
let rate_limited = GenaiError::Api {
    status_code: 429,
    message: "Resource exhausted".to_string(),
    request_id: None,
    retry_after: Some(std::time::Duration::from_secs(60)),
};
assert!(rate_limited.is_retryable());

// Bad request errors are not retryable
let bad_request = GenaiError::Api {
    status_code: 400,
    message: "Invalid model".to_string(),
    request_id: None,
    retry_after: None,
};
assert!(!bad_request.is_retryable());

// Timeouts are retryable
let timeout = GenaiError::Timeout(Duration::from_secs(30));
assert!(timeout.is_retryable());

Retry Strategy

When implementing retry logic, consider:

• Use exponential backoff with jitter
• Set a maximum number of retries
• For 429 errors, use the retry_after field if available (extracted from Retry-After header)
• Log retries for observability

See examples/retry_with_backoff.rs for a complete retry implementation.

pub fn retry_after(&self) -> Option<Duration>

Returns the server-suggested retry delay for rate limit (429) errors.

This extracts the Retry-After header value that was parsed when the error was created. Only Api errors with status code 429 typically have this field set.

Returns

• Some(Duration) if the error has a retry_after value
• None for all other error types or if no Retry-After header was present

Example

use genai_rs::GenaiError;
use std::time::Duration;

async fn with_server_suggested_delay(error: &GenaiError) {
    if let Some(delay) = error.retry_after() {
        // Server told us how long to wait
        tokio::time::sleep(delay).await;
    } else {
        // Fall back to our own backoff strategy
        tokio::time::sleep(Duration::from_secs(1)).await;
    }
}

Trait Implementations

impl Debug for GenaiError

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

Formats the value using the given formatter.

impl Display for GenaiError

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

Formats the value using the given formatter.

impl Error for GenaiError

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<Error> for GenaiError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for GenaiError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Utf8Error> for GenaiError

fn from(source: Utf8Error) -> Self

Converts to this type from the input type.