Enum FetchError 

#[non_exhaustive]
pub enum FetchError {
    UnsupportedType(String),
    MissingField(&'static str),
    Download(String),
    Throttled {
        url: String,
        status: u16,
        retry_after: Option<u64>,
    },
    Unauthorized {
        url: String,
        status: u16,
    },
    NotFound {
        url: String,
    },
    UnexpectedStatus {
        url: String,
        status: u16,
    },
    Io(Error),
    Extract(String),
}

Errors that can occur during input fetching.

Why the HTTP failures are separate variants

Every network failure used to collapse into FetchError::Download, a single String. The status code was known — it was read as a u16 and immediately formatted into prose — so a rate-limit and a missing repository arrived at the caller as the same shape, distinguishable only by matching English text.

That cost real work, measured 2026-08-17: GitHub throttled a flake input’s archive on one host while the API quota showed 4653/5000 remaining (a per-egress-IP limit on archive generation, unaffected by holding a valid token), and two full rebuilds died before the cause was understood. The remedy for a throttle is unlike the remedy for anything else here — another egress can fetch the identical bytes, and flake.lock’s pinned narHash makes “identical” checkable rather than merely hoped-for — so a consumer has to be able to branch on it. A downstream tool (pleme-io/fleet’s warm-inputs) was reduced to contains("HTTP error 429") on this crate’s own error text for exactly that reason.

So: no status is discarded, and FetchError::UnexpectedStatus exists so that adding a new HTTP behaviour cannot silently fall back into a prose bucket — an unclassified code still arrives as a number.

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.

UnsupportedType(String)

MissingField(&'static str)

Download(String)

A genuine transport failure — DNS, TLS, connect timeout, body read. Not a status: an HTTP response that arrived and said “no” is one of the four typed variants below.

Throttled

The upstream refused to serve content it has: HTTP 429, or a 403 whose body names a secondary rate limit. retry_after carries the server’s own Retry-After in seconds when it sent one — the only authority on how long to wait, and previously thrown away unread.

Fields

url: String

status: u16

retry_after: Option<u64>

Unauthorized

401 or 403 — our credential, not the content. Another egress does not help; the token does.

Fields

url: String

status: u16

NotFound

404. For a private input this is frequently an auth failure wearing a not-found mask, which is why the message says so rather than asserting the content is absent.

Fields

url: String

UnexpectedStatus

Any other non-2xx. Carries the code so an unhandled status is still a number a caller can act on, never prose.

Fields

url: String

status: u16

Io(Error)

Extract(String)

Implementations

impl FetchError

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

The HTTP status, when this failure carried one.

Exists so a caller branches on a number rather than re-deriving one from the Display text — which is the habit this enum was widened to end.

pub fn is_throttled(&self) -> bool

Whether fetching the identical bytes from a different network egress could succeed.

True only for a throttle. A 401/403/404 is about our credential or the content, so another host is refused identically — and answering true there would send an operator to build a second fetch path that cannot work.

Trait Implementations

impl Debug for FetchError

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

Formats the value using the given formatter.

impl Display for FetchError

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

Formats the value using the given formatter.

impl Error for FetchError

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 FetchError

fn from(source: Error) -> Self

Converts to this type from the input type.