Enum GithubError 

pub enum GithubError {
    AuthenticationFailed,
    AuthenticationLockout {
        retry_after: Duration,
    },
    Forbidden {
        method: String,
        path: String,
        message: Option<String>,
        headers: Box<HeaderMap>,
    },
    Status {
        status: u16,
        method: String,
        path: String,
        message: Option<String>,
        headers: Box<HeaderMap>,
    },
    Transport(Error),
    Decode {
        what: &'static str,
        expected: &'static str,
        source: Error,
    },
    Malformed {
        what: &'static str,
        value: String,
    },
    Config(ConfigError),
}

Everything AuthenticatedClient can fail with.

The first three variants are the taxonomy 03-control-flows.md flow 4.3 requires, and they are separate variants because c3 and f1 both act on the distinction: GithubError::AuthenticationFailed moves a policy to authentication_failed and tells the operator to run auth login, GithubError::AuthenticationLockout must wait and tell the operator nothing is wrong with their credential, and GithubError::Forbidden is a permissions answer that re-authenticating will not change.

Why the failing variants carry response headers

Rate-limit policy is c3’s and is deliberately not implemented here. But a policy needs evidence, and the evidence — retry-after, x-ratelimit-remaining, x-ratelimit-reset — only exists on the response that failed. An error taxonomy that dropped those headers would leave c3 with no way to honour a 429 except by editing this file, which is exactly the conflict the c2/c3 ownership split exists to prevent. So GithubError::Status and GithubError::Forbidden carry the headers verbatim and interpret none of them; see GithubError::headers.

Variants

AuthenticationFailed

GitHub rejected the credential and a single re-validation confirmed it. Terminal: only an interactive auth login clears this.

AuthenticationLockout

GitHub answered 403 after 401s — its temporary authentication lockout, not a permissions change. Back off; do not re-authenticate and do not retry.

Fields

retry_after: Duration

Forbidden

A 403 that is not the lockout: a permissions answer, or GitHub’s own rate limit. c3 tells the two apart from headers; this crate does not, because which of them is worth retrying is rate-limit policy.

Fields

method: String

path: String

message: Option<String>

headers: Box<HeaderMap>

The response headers, verbatim and uninterpreted.

Status

Fields

status: u16

method: String

path: String

message: Option<String>

headers: Box<HeaderMap>

The response headers, verbatim and uninterpreted. A 429 reaches c3 through this variant, and its retry-after survives with it.

Transport(Error)

The request never got an answer. The URL is stripped from the source error before it is stored: a device-flow URL never carries a secret, but stripping it costs nothing and removes a whole class of future leak.

Decode

Fields

what: &'static str

expected: &'static str

source: Error

Malformed

Fields

what: &'static str

value: String

Config(ConfigError)

Implementations

impl GithubError

pub fn is_authentication(&self) -> bool

true for the two authentication outcomes, which callers handle differently from every other failure.

pub fn is_lockout(&self) -> bool

true only for the lockout, which is the one authentication outcome that resolves by waiting rather than by signing in again.

pub fn headers(&self) -> Option<&HeaderMap>

The failing response’s headers, for the variants that have them.

This is the whole of c2’s contribution to rate limiting: it hands c3 the evidence and stops there. Nothing in this crate reads x-ratelimit-remaining to decide anything.

pub fn retry_after(&self) -> Option<Duration>

The failing response’s retry-after, in seconds, if it sent one.

Reading a documented header is evidence, not policy: what to do with a retry-after — wait, shed load, surface it to an operator — is c3’s.

pub fn rate_limit(&self) -> Option<RateLimitEvidence>

The x-ratelimit-remaining / x-ratelimit-reset pair, when present.

Returned as the raw numbers GitHub sent. reset is a Unix timestamp in seconds, which is what the header carries; it is deliberately not turned into a Timestamp here, because comparing it against a clock is the first step of a policy decision and that decision is c3’s.

Trait Implementations

impl Debug for GithubError

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

Formats the value using the given formatter.

impl Display for GithubError

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

Formats the value using the given formatter.

impl Error for GithubError

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<ConfigError> for GithubError

fn from(source: ConfigError) -> Self

Converts to this type from the input type.

impl From<GithubError> for JitError

fn from(source: GithubError) -> Self

Converts to this type from the input type.

impl From<GithubError> for InventoryError

fn from(source: GithubError) -> Self

Converts to this type from the input type.