Enum ClientError 

#[non_exhaustive]
pub enum ClientError {
    Request(Error),
    Json(Error),
    NoMock(String, String),
    CircuitBreakerOpen,
    FaultInjected(String),
    ThrottledLocally {
        host: String,
    },
    ReplayedRequestFailure(String),
    BlockedDuringReplay(String, String),
    SsrfBlocked(String),
    TooManyRedirects(usize),
    RedirectRejected(String),
    InvalidUrl(String),
    IncompatiblePinRedirect(&'static str),
    PinRequiresDomainHost(&'static str),
    PinNotAllowedWithSsrfSafe(&'static str),
    SimNetwork(String),
    DeadlineExceeded,
}

Errors produced by Client and RequestBuilder.

#[non_exhaustive]: match it with a _ arm, so a new variant is not a breaking change.

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.

Request(Error)

An underlying reqwest transport error.

Json(Error)

JSON (de)serialisation failed.

NoMock(String, String)

No mock entry matched the outgoing request.

CircuitBreakerOpen

The outbound circuit breaker is open.

FaultInjected(String)

A staging fault ([fault_injection], target http) failed the call before it was sent.

ThrottledLocally

The client-side adaptive throttle rejected the attempt locally, because the host rejected too many recent attempts (issue #3068). See [http.client.adaptive_throttle].

Fields

host: String

The host (host or host:port).

ReplayedRequestFailure(String)

The capsule recorded a transport failure for this call, and replay reproduced it (#1634).

A recorded transport error cannot be rebuilt as a reqwest::Error — it has no public constructor — but it must not be downgraded to a status either: a handler whose bug is “we do not handle a connection reset” has to meet the reset again.

Its Display is the recorded text exactly, with no replay marker of its own. A handler that propagates this error puts the text into the capsule’s outcome, and the replay verdict compares outcome messages verbatim — so a marker here would report an unchanged failure as a mismatch, which is the one thing the comparison exists to get right.

BlockedDuringReplay(String, String)

Outbound HTTP is blocked because this process is replaying a failure capsule (see the crate-internal block_outbound_for_replay).

SsrfBlocked(String)

A resolved connection target (or redirect target) is a blocked (private / link-local / loopback / reserved) IP address per the built-in SSRF policy. See is_blocked_ip.

TooManyRedirects(usize)

A redirect chain exceeded the configured maximum number of hops.

RedirectRejected(String)

A redirect’s absolute Location target was rejected by the caller’s validator (or by the built-in scheme-downgrade guard).

InvalidUrl(String)

A URL could not be parsed, was missing a host, or DNS resolution failed while composing a custom (redirect / pin / SSRF-safe) request.

IncompatiblePinRedirect(&'static str)

pin_to was combined with follow_redirects — an incompatible pair. A single pinned SocketAddr only covers the first hop; later redirect hops re-resolve via normal DNS, so following a cross-host 3xx would silently escape the pin and defeat its purpose. Use Client::get_ssrf_safe for pinned, per-hop-revalidated redirect following; pin_to alone (returns the 3xx unfollowed); or follow_redirects without pin_to.

PinRequiresDomainHost(&'static str)

pin_to was used on a request whose URL host is an IP literal. reqwest/hyper treat an IP-literal host as already-resolved and never consult the DNS resolver, so the resolve_to_addrs override that installs the pin is skipped and the socket connects to the literal in the URL — not the pinned address — silently bypassing the pin. pin_to therefore requires a domain (hostname) host; put the desired IP directly in the URL, or use a domain host. (get_ssrf_safe never sets a pin: it validates the literal and connects to that same IP, so it is unaffected.)

PinNotAllowedWithSsrfSafe(&'static str)

pin_to was combined with Client::get_ssrf_safe — an incompatible pair. The SSRF-safe path runs its own per-hop resolve→validate→pin and never reads the caller’s pin_to address, so an explicit pin would be silently ignored. Use pin_to alone for a caller-chosen fixed address, or get_ssrf_safe alone for guarded automatic per-hop pinning — not both.

SimNetwork(String)

The simulated network (crate::sim::SimNet, issue #2967) failed the call: a drop, a partition, a timeout, a host it does not know, or a request or response it could not build.

DeadlineExceeded

The request deadline passed before an attempt could start (issue #3058). See crate::deadline.

Trait Implementations

impl Debug for ClientError

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

Formats the value using the given formatter.

impl Display for ClientError

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

Formats the value using the given formatter.

impl Error for ClientError

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 ClientError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for ClientError

fn from(source: Error) -> Self

Converts to this type from the input type.