Enum Error 

pub enum Error {
    InvalidBaseUrl(ParseError),
    Transport {
        kind: TransportKind,
        message: String,
        source: Option<Arc<dyn Error + Send + Sync>>,
    },
    Http {
        status: StatusCode,
        status_text: String,
        message: String,
        body: Option<Bytes>,
    },
    Deserialize {
        status: StatusCode,
        message: String,
        body: Option<Bytes>,
    },
    Validation {
        status: StatusCode,
        message: String,
        body: Option<Bytes>,
    },
    Timeout,
    Cancelled,
    BodyTooLarge {
        limit: u64,
    },
    MissingBaseUrl,
    RetryExhausted {
        attempts: u32,
        last: Option<Box<Error>>,
    },
    Hook(String),
    QuerySerialize(String),
    InvalidHeaderName(String),
    InvalidHeaderValue(String),
    MissingPathParam(String),
    SchemaRoute {
        method: String,
        path: String,
    },
    SchemaValidation {
        phase: &'static str,
        message: String,
    },
    InvalidAuthHeader(String),
    NonReplayableBody,
    RequestValidation {
        message: String,
    },
    Io(String),
    Config(String),
    Other(String),
}

Error type for better-fetch operations.

Variants

InvalidBaseUrl(ParseError)

Base URL parsing failed (ClientBuilder::base_url).

Transport

Underlying transport failure (connection, DNS, body read, etc.).

Fields

kind: TransportKind

Coarse category aligned with reqwest’s is_* helpers.

message: String

Human-readable detail (typically from the underlying error’s Display).

source: Option<Arc<dyn Error + Send + Sync>>

Underlying error when available (e.g. reqwest).

Http

Non-success HTTP response (when using throw mode or send_json).

Fields

status: StatusCode

HTTP status code.

status_text: String

Canonical reason phrase.

message: String

Human-readable message.

body: Option<Bytes>

Response body when buffered.

Deserialize

Available on crate feature json only.

JSON response could not be deserialized (feature json).

Fields

status: StatusCode

message: String

body: Option<Bytes>

Validation

Available on crate feature validate only.

Response failed garde validation (feature validate).

Fields

status: StatusCode

message: String

body: Option<Bytes>

Timeout

Request exceeded the configured timeout.

Cancelled

Request was cancelled via CancellationToken.

BodyTooLarge

Response body exceeded ClientBuilder::max_response_bytes or a per-request RequestBuilder::max_response_bytes limit on buffered (send / send_json) or streaming responses.

Fields

limit: u64

Configured maximum response size in bytes.

MissingBaseUrl

ClientBuilder::build without ClientBuilder::base_url.

RetryExhausted

Transport retries were exhausted.

Fields

attempts: u32

Total attempts made (initial + retries).

last: Option<Box<Error>>

Last error before retries were exhausted, when available.

Hook(String)

Returned from on_request or on_response to abort the pipeline. Prefer constructing this with Error::hook rather than Error::Other.

QuerySerialize(String)

Query parameter serialization failed (typed endpoint query).

Returned from EndpointRequestBuilder::query and EndpointQuery::apply_query when serde serialization fails (since 0.4.0).

InvalidHeaderName(String)

Invalid HTTP header name (RequestBuilder::header).

InvalidHeaderValue(String)

Invalid HTTP header value (RequestBuilder::header).

MissingPathParam(String)

A :param segment in the path template was not supplied.

SchemaRoute

Route not registered in a strict SchemaRegistry (feature schema).

Fields

method: String

HTTP method.

path: String

Path template.

SchemaValidation

Available on crate feature schema-validate only.

JSON Schema validation failed (feature schema-validate).

Fields

phase: &'static str

"request" or "response".

message: String

Validator detail.

InvalidAuthHeader(String)

Invalid Authorization header value.

NonReplayableBody

Request body cannot be replayed for automatic retry (stream or multipart).

RequestValidation

Available on crate feature validate only.

Request body failed validation before send (feature validate).

Fields

message: String

Validation error detail.

Io(String)

I/O error (file writes, etc.).

Config(String)

Internal client configuration error.

Other(String)

Catch-all for rare plugin errors.

Implementations

impl Error

pub fn transport(kind: TransportKind, message: impl Into<String>) -> Self

Builds a transport error with an explicit TransportKind.

pub fn transport_with_source( kind: TransportKind, message: impl Into<String>, source: impl Error + Send + Sync + 'static, ) -> Self

Builds a transport error with an underlying source error.

pub fn transport_message(message: impl Into<String>) -> Self

Builds a transport error with TransportKind::Other.

pub fn transport_source(&self) -> Option<&(dyn Error + Send + Sync)>

Returns the transport error source when present.

pub fn transport_kind(&self) -> Option<TransportKind>

Returns the transport failure category when this error is Error::Transport.

pub fn transport_detail(&self) -> Option<&str>

Returns the transport error detail string when this error is Error::Transport.

pub fn is_transport(&self) -> bool

Returns true when this error is Error::Transport.

pub fn is_timeout(&self) -> bool

Returns true when this error is Error::Timeout.

pub fn http( status: StatusCode, message: impl Into<String>, body: Option<Bytes>, ) -> Self

Builds an HTTP error with canonical status text.

pub fn http_with_status_text( status: StatusCode, status_text: impl Into<String>, message: impl Into<String>, body: Option<Bytes>, ) -> Self

Builds an HTTP error with explicit status text.

pub fn query_serialize(message: impl Into<String>) -> Self

Builds a query serialization error.

pub fn status(&self) -> Option<StatusCode>

Returns the HTTP status when this error is response-related.

pub fn status_text(&self) -> Option<&str>

Returns the canonical status text for Error::Http.

pub fn body(&self) -> Option<&Bytes>

Returns the response body when present on HTTP, deserialize, or validation errors.

pub fn is_retry_exhausted(&self) -> bool

Returns true when transport retries were configured but all attempts failed.

pub fn retry_exhausted_last(&self) -> Option<&Error>

Returns the last error from Error::RetryExhausted when present.

pub fn is_cancelled(&self) -> bool

Returns true when the request was cancelled via CancellationToken.

pub fn is_body_too_large(&self) -> bool

Returns true when the response body exceeded a configured size limit.

pub fn body_too_large_limit(&self) -> Option<u64>

Returns the configured byte limit when this error is Error::BodyTooLarge.

pub fn hook(msg: impl Into<String>) -> Self

Builds a hook failure for Hooks::on_request / Hooks::on_response.

pub fn is_hook(&self) -> bool

Returns true when the error is Error::Hook.

pub fn api_json<T: DeserializeOwned>(&self) -> Option<T>

Available on crate feature json only.

Parses the error response body as JSON (for API error payloads).

Examples

use better_fetch::Error;
use http::StatusCode;
use serde::Deserialize;

#[derive(Debug, Deserialize, PartialEq)]
struct ApiError {
    message: String,
}

let err = Error::http_with_status_text(
    StatusCode::BAD_REQUEST,
    "Bad Request",
    "bad request",
    Some(bytes::Bytes::from_static(br#"{"message":"invalid"}"#)),
);
let api: ApiError = err.api_json().unwrap();
assert_eq!(api.message, "invalid");

pub fn api_json_validated<T>(&self) -> Option<T>

where T: DeserializeOwned + Validate, T::Context: Default,

Available on crate feature validate only.

Parses and validates the error response body (feature validate).

Trait Implementations

impl Clone for Error

fn clone(&self) -> Error

Returns a duplicate of the value.

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

Performs copy-assignment from source.

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

Available on crate feature miette only.

fn from(inner: Error) -> Self

Converts to this type from the input type.

impl From<ParseError> for Error

fn from(source: ParseError) -> Self

Converts to this type from the input type.