modelbridge 0.5.2

One provider-neutral Rust client for OpenAI, Anthropic, Gemini, Groq, Ollama and friends: streaming, tool calling, an agent loop, usage accounting, and subscription sign-in
Documentation
//! One error type for every way a model call can go wrong.
//!
//! Callers that still work in `Result<_, String>` lose nothing: [`Error`]
//! converts with `?` through [`From<Error> for String`](#impl-From<Error>-for-String).

use std::fmt;
use std::time::Duration;

/// Why a request failed.
///
/// The variants exist to be matched on, not just printed: retry policy,
/// credential refresh, and user-facing wording all key off the distinction
/// between a rejected credential, a rate limit, and a broken connection.
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum Error {
    /// The route could not be built: unknown provider, missing key variable,
    /// malformed URL. Always a programming or configuration mistake.
    Config(String),
    /// The server rejected the credential (401/403), and it could not be
    /// refreshed.
    Auth(String),
    /// The server asked for less traffic (429), optionally saying for how long.
    RateLimited {
        message: String,
        retry_after: Option<Duration>,
    },
    /// Any other non-success status, with the vendor's own wording.
    Api { status: u16, message: String },
    /// The request never reached the server, or the connection died.
    Network(String),
    /// The connection survived but the event stream did not.
    Stream(String),
    /// The server answered in a shape this crate does not recognise.
    Decode(String),
    /// The caller's cancellation flag was raised.
    Cancelled,
}

impl Error {
    /// Whether sending the same request again could plausibly succeed.
    ///
    /// Rate limits and transient server faults qualify; a rejected key or a
    /// malformed request does not, and retrying those only wastes a quota.
    pub fn retryable(&self) -> bool {
        match self {
            Error::RateLimited { .. } | Error::Network(_) | Error::Stream(_) => true,
            Error::Api { status, .. } => matches!(status, 408 | 409 | 500 | 502 | 503 | 504),
            _ => false,
        }
    }

    /// Whether refreshing a credential is the right response.
    pub fn is_auth(&self) -> bool {
        matches!(self, Error::Auth(_))
    }

    /// How long the server asked us to wait, when it said.
    pub fn retry_after(&self) -> Option<Duration> {
        match self {
            Error::RateLimited { retry_after, .. } => *retry_after,
            _ => None,
        }
    }

    /// The HTTP status behind this error, when there was one.
    pub fn status(&self) -> Option<u16> {
        match self {
            Error::Api { status, .. } => Some(*status),
            Error::RateLimited { .. } => Some(429),
            _ => None,
        }
    }
}

impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Error::Config(message) => write!(f, "{message}"),
            Error::Auth(message) => write!(f, "{message}"),
            Error::RateLimited {
                message,
                retry_after,
            } => match retry_after {
                Some(wait) => write!(f, "rate limited, retry in {}s: {message}", wait.as_secs()),
                None => write!(f, "rate limited: {message}"),
            },
            Error::Api { status, message } => write!(f, "HTTP {status}: {message}"),
            Error::Network(message) => write!(f, "network: {message}"),
            Error::Stream(message) => write!(f, "stream: {message}"),
            Error::Decode(message) => write!(f, "unexpected response: {message}"),
            Error::Cancelled => write!(f, "cancelled"),
        }
    }
}

impl std::error::Error for Error {}

/// Applications built around `Result<_, String>` keep using `?` unchanged.
impl From<Error> for String {
    fn from(error: Error) -> String {
        error.to_string()
    }
}

/// A short-hand for the crate's fallible operations.
pub type Result<T> = std::result::Result<T, Error>;

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn only_transient_failures_are_worth_repeating() {
        assert!(Error::RateLimited {
            message: "slow down".into(),
            retry_after: Some(Duration::from_secs(3))
        }
        .retryable());
        assert!(Error::Api {
            status: 503,
            message: "overloaded".into()
        }
        .retryable());
        assert!(Error::Network("connection reset".into()).retryable());

        assert!(!Error::Auth("bad key".into()).retryable());
        assert!(!Error::Api {
            status: 400,
            message: "bad request".into()
        }
        .retryable());
        assert!(!Error::Cancelled.retryable());
    }

    #[test]
    fn a_rate_limit_carries_the_wait_the_server_asked_for() {
        let error = Error::RateLimited {
            message: "quota".into(),
            retry_after: Some(Duration::from_secs(12)),
        };
        assert_eq!(error.retry_after(), Some(Duration::from_secs(12)));
        assert_eq!(error.status(), Some(429));
        assert!(error.to_string().contains("retry in 12s"));
    }

    #[test]
    fn string_callers_keep_working() {
        fn legacy() -> std::result::Result<(), String> {
            Err(Error::Auth("expired".into()))?;
            Ok(())
        }
        assert_eq!(legacy().unwrap_err(), "expired");
    }
}