Enum ProviderErrorKind 

pub enum ProviderErrorKind {
    Transport,
    Timeout,
    RateLimited,
    Server,
    Auth,
    Request,
    Malformed,
}

Why a provider call failed, and therefore whether trying it again — or trying a different provider — is worth doing.

Before 0.11.0 every provider failure was one string: a 429, a 503, a 401 and a DNS failure differed only in prose, so nothing above the provider could branch on them. This enum is that branch, and ProviderErrorKind::is_retryable is the decision the rest of the crate reads.

A caller branches on the kind rather than on the message, because the message wording is explicitly not part of the public contract and the kind is:

use io_harness::{Error, ProviderErrorKind};
use std::time::Duration;

// What a run that exhausted its retries hands back. The three answers a
// caller actually has are "wait this long", "try again now", and "stop".
match failure {
    // The only kind that carries *when*. Honour the server's own number
    // rather than backing off blind, then resume under the original run id.
    Error::Provider { kind: ProviderErrorKind::RateLimited, retry_after, .. } => {
        ("wait, then resume", Some(retry_after.unwrap_or(Duration::from_secs(30))))
    }
    // Auth and Request are terminal: the key will not become valid, and the
    // server has already read this exact request and refused it. Retrying
    // burns the budget to reach the same failure and hides it behind a later one.
    Error::Provider { kind, .. } if !kind.is_retryable() => ("stop and page a human", None),
    Error::Provider { .. } => ("resume; another attempt can succeed", None),
    _ => ("not a provider failure", None),
}

Variants

Transport

The request never completed: connection refused, DNS failure, TLS failure, a mid-stream byte error.

Timeout

The request had a deadline and passed it.

RateLimited

429. Carries the server’s Retry-After when it sent one.

Server

5xx.

Auth

401 or 403 — the key is wrong, missing, or not entitled to this model.

Request

4xx other than 401/403: the request itself is unacceptable.

Malformed

The response arrived and nothing in it could be read.

Implementations

impl ProviderErrorKind

pub fn is_retryable(self) -> bool

Whether re-sending the same request could plausibly succeed.

Per arm, and the reasoning is the point — a retry that cannot work costs the budget twice and hides the real failure behind a later one:

• Transport: the request never reached the model, so nothing about it was rejected. Networks drop connections for reasons that do not repeat.
• Timeout: the deadline says nothing about the request. A hung socket or an overloaded server is the usual cause and neither is permanent.
• RateLimited: the server is explicitly telling you to come back later. This is the one kind that carries when.
• Server: a 5xx is the server’s own admission that the fault is its side, not the request’s.
• Malformed: a garbled or empty stream is far more often a truncated transfer than a model that genuinely produced nothing, and re-asking is cheap — cheaper than a run that reads the emptiness as “the model chose not to call a tool” and quietly stops.
• Auth: the key will not become valid between two calls a second apart. Retrying burns the retry budget to reach the same 401.
• Request: the server has already read this exact request and refused it. Sending it again is two failures instead of one.

pub fn from_status(status: u16) -> Self

The kind an HTTP status maps to.

The one place that mapping lives, so OpenRouter, OpenAI and Anthropic cannot drift apart: they were byte-identical before this existed and this is what keeps them so. A status the buckets do not cover (1xx, 3xx — the client follows no redirects, so a 3xx is a boundary hop, not a success) is Request: unexpected, and not something a retry fixes.

Trait Implementations

impl Clone for ProviderErrorKind

fn clone(&self) -> ProviderErrorKind

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for ProviderErrorKind

impl Debug for ProviderErrorKind

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

Formats the value using the given formatter.

impl Eq for ProviderErrorKind

impl PartialEq for ProviderErrorKind

fn eq(&self, other: &ProviderErrorKind) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for ProviderErrorKind