Enum ErrorCode 

#[non_exhaustive]
pub enum ErrorCode {
    InvalidRef,
    NoOaAvailable,
    RateLimited,
    NetworkError,
    NotFound,
    Ambiguous,
    StoreError,
    LogError,
    CapabilityDenied,
    FetchTimeout,
    SchemaTooNew,
    LockTimeout,
    InternalError,
    NotImplemented,
    TextUnavailable,
}

The closed set of error codes doiget surfaces.

See docs/ERRORS.md for the persona × code matrix.

Marked #[non_exhaustive] so adding new variants is a minor (not major) version bump.

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.

InvalidRef

DOI / arXiv id failed validation.

NoOaAvailable

Tier 1 sources reported no OA URL.

RateLimited

Internal rate cap or upstream 429.

NetworkError

Transport / DNS / TLS failure.

NotFound

A metadata source authoritatively reported that the identifier does not exist. Network-independent and reproducible, so doiget verify treats it as a definite dead reference (fails the run even without --strict) rather than a tolerable blip — distinct from the transient Self::NetworkError, Self::RateLimited, and Self::FetchTimeout.

Sources: an HTTP 404 / 410 / 451 from a metadata API, or a source-specific absence signal (e.g. arXiv returns HTTP 200 with an empty <feed> for an unknown id, surfaced via FetchError::NotFound).

Caveat (DOI fan-out): for a DOI this is emitted only when the configured metadata sources (Crossref, then Unpaywall) all fail to resolve it and at least one authoritatively 404s. A DOI registered only outside that set (e.g. a DataCite-only dataset DOI) can therefore be reported NotFound even though it exists in a registry doiget does not query.

Ambiguous

A name filter (author / venue / publisher) matched MORE than one entity with no clear winner, so it could not be resolved to a single id. Distinct from Self::NotFound (“matched nothing”): an agent should narrow the name (add a first name / fuller title) rather than conclude the entity does not exist. The accompanying error message lists the candidate matches. Wire form: "AMBIGUOUS". Raised by doiget search’s name-filter resolution (ADR-0031 D5).

StoreError

Filesystem write failed.

LogError

Provenance log write failed; the fetch was aborted.

CapabilityDenied

Source not granted by the runtime CapabilityProfile.

FetchTimeout

Per-request timeout exceeded.

SchemaTooNew

Store entry’s schema_version is ahead of this build.

LockTimeout

Could not acquire flock within 5 s.

InternalError

Bug — please open an issue.

NotImplemented

Feature is spec’d but not yet wired in this Phase. Distinct from Self::InternalError (which signals a bug) and Self::CapabilityDenied (which signals a runtime config gate). Returned by stubs that exist to pin the public surface ahead of orchestrator implementation, so an agent can react with “wait for next minor release” rather than “report a bug” or “tweak my capability profile”. Wire form: "NOT_IMPLEMENTED".

TextUnavailable

The identifier is valid and resolvable, but the requested representation is not available from its source — currently the ar5iv HTML render consulted by doiget text (a 200 with no extractable prose: the paper was never converted to HTML).

Deliberately distinct from the neighbouring codes so an agent does not misdiagnose a missing render as a bad reference (issue #302): it is NOT Self::NotFound (the id does exist), NOT Self::NoOaAvailable (the paper may well be OA — only this one representation is missing), and NOT Self::NetworkError (the fetch succeeded). The actionable branch is “fetch the PDF instead”, not “fix the identifier”. Wire form: "TEXT_UNAVAILABLE".

Implementations

impl ErrorCode

pub fn as_wire(&self) -> &'static str

The SCREAMING_SNAKE_CASE wire token for this code, as a &'static str. Identical to the serde representation but allocation-free and usable where a borrowed string with a 'static lifetime is required — notably the provenance log error_code column (docs/PROVENANCE_LOG.md §3), so a failure row records the actual mapped code instead of a hand-written literal that can drift from this enum (issue #118).

Trait Implementations

impl Clone for ErrorCode

fn clone(&self) -> ErrorCode

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for ErrorCode

impl Debug for ErrorCode

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ErrorCode

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for ErrorCode

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 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<RefParseError> for ErrorCode

fn from(_: RefParseError) -> Self

Converts to this type from the input type.

impl Hash for ErrorCode

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for ErrorCode

fn eq(&self, other: &ErrorCode) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for ErrorCode

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for ErrorCode