Enum FetchError 

#[non_exhaustive]
pub enum FetchError {
    NotEligible {
        source_key: String,
    },
    NoOaAvailable,
    NotFound {
        hint: String,
    },
    Ambiguous {
        hint: String,
    },
    Http(HttpError),
    Log(LogError),
    InvalidRef(RefParseError),
    SourceSchema {
        hint: String,
    },
    TooManyRefs {
        got: usize,
        max: usize,
    },
    TextUnavailable {
        arxiv_id: ArxivId,
    },
    SourceUnavailable {
        arxiv_id: ArxivId,
        kind: &'static str,
    },
}

Errors returned by Source::fetch.

At the public CLI / MCP boundary, every variant collapses to an crate::ErrorCode via the From<FetchError> impl below — mirroring the RefParseError → crate::ErrorCode::InvalidRef collapse from PR #55.

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.

NotEligible

The source does not handle the given ref under the runtime capability profile (covers both can_serve = false outcomes and runtime denials raised inside fetch).

Fields

source_key: String

The source key that declined.

NoOaAvailable

Tier 1 sources reported no OA URL for this ref.

NotFound

A metadata source authoritatively reported that the identifier does not exist — distinct from a transport failure. Surfaces as crate::ErrorCode::NotFound. Used for sources whose “absent” signal is NOT an HTTP 404/410 (e.g. the arXiv Atom API returns HTTP 200 with an empty <feed> for an unknown id).

Fields

hint: String

Human-readable detail (which source, and how it signalled absence); not parsed.

Ambiguous

A name filter (author / venue / publisher) matched MORE than one OpenAlex entity with no clear winner. Carries a candidate listing so the caller can narrow the name (or pass an explicit id). Collapses to crate::ErrorCode::Ambiguous (wire "AMBIGUOUS") — distinct from NotFound so an agent narrows rather than gives up. Used by crate::discovery.

Fields

hint: String

Human-readable candidate listing; not parsed.

Http(HttpError)

Underlying HTTP / network failure. See HttpError.

Log(LogError)

Provenance log write failed. Per docs/SECURITY.md §1.8 this is a fail-closed signal; the surrounding fetch MUST be aborted.

InvalidRef(RefParseError)

Ref re-parse / validation failed inside the source (e.g. when a source receives a borrowed string from upstream and re-validates).

SourceSchema

Source-side schema mismatch (unexpected JSON shape, missing required field). Surfaces to crate::ErrorCode::InternalError at the public boundary.

Fields

hint: String

Human-readable hint at the offending field/path; not parsed.

TooManyRefs

Batch orchestrator received more refs than crate::MAX_BATCH_REFS. Surfaced to the MCP doiget_batch_fetch tool as ErrorCode::InvalidRef (closest closed-set fit — the request shape itself is invalid; no denial_context channel applies). Slice 2 / docs/MCP_TOOLS.md §1.

Fields

got: usize

Number of refs the batch orchestrator was handed.

max: usize

The hard cap (crate::MAX_BATCH_REFS).

TextUnavailable

A source returned a successful response that contained no usable representation of the requested kind — currently doiget text’s ar5iv leg returning a 200 with no extractable prose (the paper was never converted to HTML). The identifier is valid; only this one representation is missing. Surfaces as crate::ErrorCode::TextUnavailable so an agent fetches the PDF instead of concluding the reference is wrong (issue #302) — NOT Self::NotFound, which means the id itself does not exist.

Fields

arxiv_id: ArxivId

The arXiv id whose ar5iv render was empty; echoed into the human/MCP message so the actionable doiget fetch <id> hint is self-contained. A validated crate::ArxivId (review #318) — the id was already parsed, so the error cannot carry a malformed string into the actionable doiget fetch <id> hint.

SourceUnavailable

A source returned a successful response that contained no file of the requested kind for doiget source — a PDF-only / single-file submission (no multi-file bundle), or --figures-only on a submission with no image files. The identifier is valid; only the bundle / figure representation is absent. Surfaces as crate::ErrorCode::TextUnavailable (same “this representation is missing; the PDF may be fetchable” class as Self::TextUnavailable), but as a DISTINCT variant so the message is not ar5iv-specific (issue #343 / ADR-0034; PR review).

Fields

arxiv_id: ArxivId

The arXiv id whose source bundle / figures were absent.

kind: &'static str

Which representation was requested: "source bundle" or "figures".

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<&FetchError> for ErrorCode

Borrow-form of the collapse above, so a caller that still needs the error for its Display message / denial_context side-channel (notably the CLI human-persona renderer, issue #119) can obtain the closed code without consuming it. The owned impl delegates here so the mapping table lives in exactly one place.

fn from(e: &FetchError) -> ErrorCode

Converts to this type from the input type.

impl From<&FetchError> for Option<DenialContext>

Map a FetchError reference to the structured crate::DenialContext channel introduced by ADR-0023 §4.

&FetchError (rather than FetchError) so the orchestrator can produce the structured side-channel without consuming the error it still needs for error.message and the From<FetchError> for ErrorCode collapse above. The Http arm delegates to the From<&HttpError> for Option<DenialContext> impl in crate::http.

fn from(e: &FetchError) -> Self

Converts to this type from the input type.

impl From<FetchError> for ErrorCode

Map FetchError to the closed crate::ErrorCode set surfaced at the public CLI / MCP boundary. Mirrors the From<RefParseError> for ErrorCode collapse from PR #55.

fn from(e: FetchError) -> ErrorCode

Converts to this type from the input type.

impl From<HttpError> for FetchError

fn from(source: HttpError) -> Self

Converts to this type from the input type.

impl From<LogError> for FetchError

fn from(source: LogError) -> Self

Converts to this type from the input type.

impl From<RefParseError> for FetchError

fn from(source: RefParseError) -> Self

Converts to this type from the input type.