Enum Error 

#[non_exhaustive]
pub enum Error {
    StackBuild {
        retryable: bool,
        source: Box<dyn StdError + Send + Sync>,
    },
    Resolution {
        host: String,
        retryable: bool,
        source: ResolveError,
    },
    Connect {
        host: String,
        port: u16,
        source: Box<dyn StdError + Send + Sync>,
    },
    Tls {
        host: String,
        source: Box<dyn StdError + Send + Sync>,
    },
    StreamReset {
        code: u64,
    },
    Protocol {
        source: Box<dyn StdError + Send + Sync>,
    },
    ConnectionLimit,
    TunnelRefused {
        status: StatusCode,
    },
    BodyTooLarge {
        limit: usize,
    },
    Timeout {
        phase: TimeoutPhase,
        timeout: Duration,
    },
    InvalidBody {
        source: FromUtf8Error,
    },
    InvalidRequest {
        reason: Cow<'static, str>,
    },
    Closed,
}

Any failure on the request path.

The variants follow the phases of a request: building connectivity, resolving the origin, connecting to it, and exchanging the request and response. is_retryable classifies each error once, so callers branch on that instead of re-deriving the answer from the variant.

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.

StackBuild

Building SCION connectivity (the stack or the resolver) failed.

Fields

retryable: bool

Whether retrying may succeed (all underlying failures were transient).

source: Box<dyn StdError + Send + Sync>

The underlying cause.

Resolution

SCION name resolution for the origin’s host failed: the DNS lookup itself failed, or the host has no valid TSAR TXT records.

Fields

host: String

The host that failed to resolve.

retryable: bool

Whether retrying may succeed (the lookup failed, as opposed to the host having no valid records).

source: ResolveError

The underlying resolver error.

Connect

No connection to the origin could be established: every candidate address failed with a socket, QUIC, or handshake error.

Fields

host: String

The origin’s host.

port: u16

The origin’s port.

source: Box<dyn StdError + Send + Sync>

The underlying cause(s).

Tls

The TLS layer rejected the origin: every candidate negotiated an ALPN other than HTTP/3.

A certificate that fails to validate does not land here: the transport reports it as a failed handshake, indistinguishable from an unreachable peer, so it surfaces as Connect.

Fields

host: String

The origin’s host (the certificate-validation identity).

source: Box<dyn StdError + Send + Sync>

The underlying cause.

StreamReset

The peer reset the request stream.

Fields

code: u64

The HTTP/3 application error code carried by the reset.

Protocol

An HTTP/3 protocol violation occurred on an established connection.

Fields

source: Box<dyn StdError + Send + Sync>

The underlying cause.

ConnectionLimit

The peer’s concurrent-stream limit is exhausted; the request was never sent.

TunnelRefused

The server refused the CONNECT tunnel with a non-2xx status.

Fields

status: StatusCode

The status of the CONNECT response.

BodyTooLarge

The response body exceeded the size limit passed to Response::bytes or Response::text.

Fields

limit: usize

The limit that was exceeded.

Timeout

A deadline expired.

Fields

phase: TimeoutPhase

The phase of the request that timed out.

timeout: Duration

The deadline that expired.

InvalidBody

The response body is not valid UTF-8 (only from Response::text).

Fields

source: FromUtf8Error

The underlying UTF-8 error.

InvalidRequest

The request is invalid (malformed URL, unsupported scheme, missing host, or an invalid header).

Fields

reason: Cow<'static, str>

What is wrong with the request.

Closed

The client has been closed with Client::close.

Implementations

impl Error

pub fn is_retryable(&self) -> bool

Whether retrying the request may succeed.

Transient conditions (connectivity, timeouts, stream resets, stream limits, a 5xx tunnel refusal) are retryable. Deterministic ones (TLS rejection, protocol violations, invalid requests, oversized bodies, a 4xx tunnel refusal, a closed client) are not. For StackBuild and Resolution the answer is decided when the error is constructed, from the transience of the underlying failures.

A retryable error never implies the request did not reach the server: only the caller knows whether its request is idempotent.

Trait Implementations

impl Debug for Error

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

Formats the value using the given formatter.

impl Display for Error

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

Formats the value using the given formatter.

impl Error for Error

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

fn from(error: BuildRequestError) -> Self

An invalid request is an Error::InvalidRequest, so the convenience entry points (Client::get, Client::post) report builder failures through the same taxonomy as the rest of the request path.