Enum UsageError 

#[non_exhaustive]
pub enum UsageError {
    NoCredentials,
    Credentials(CredentialError),
    Timeout,
    RateLimited {
        retry_after: Option<Duration>,
    },
    NetworkError,
    ParseError,
    Unauthorized,
    Jsonl(JsonlError),
}

Errors from the OAuth /api/oauth/usage endpoint plus the cache stack, credential, and JSONL-fallback layers that feed it. Rendered to the user via the segment error table in docs/specs/rate-limit-segments.md.

PartialEq is not derived: inner types (io::Error, serde_json::Error) don’t support it. CredentialError has a lossy Clone impl so the cascade can preserve variant-level detail across Arc<Result<_, CredentialError>> boundaries; UsageError itself isn’t Clone because DataContext memoizes it behind Arc<Result<_, UsageError>> and cross-segment sharing clones the Arc.

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.

NoCredentials

No OAuth token reachable from any cascade path. Rendered [No credentials].

Credentials(CredentialError)

Credentials-layer failure. Segment code matches on the inner variant to render [Keychain error] / [Credentials unreadable] / [No credentials] per the error table.

Timeout

Endpoint took longer than the configured timeout. Rendered [Timeout].

RateLimited

Endpoint returned 429 Too Many Requests. retry_after is the parsed Retry-After header (integer seconds or HTTP-date per ADR-0011 §Cache stack); None means the header was absent and the default 300s backoff applies. Rendered [Rate limited].

Fields

retry_after: Option<Duration>

NetworkError

Connection failed, DNS failure, TLS failure, or any other network-level error. Rendered [Network error].

ParseError

Endpoint returned malformed JSON. Rendered [Parse error].

Unauthorized

Endpoint returned 401 Unauthorized. Token is expired or revoked; Claude Code refreshes on its next request. Rendered [Unauthorized].

Jsonl(JsonlError)

JSONL-fallback-layer failure. Surfaces when the endpoint path recorded an error AND the JSONL aggregator also yielded nothing.

Implementations

impl UsageError

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

Short plugin-facing error tag per docs/specs/plugin-api.md §ctx shape exposed to rhai. Rendered in the rhai tagged-map mirror as error: "<code>". Wrapping variants (Credentials, Jsonl) delegate to the inner error’s code() so plugins see a flat taxonomy. Today those inner types are stubs that return "NotImplemented"; once the credential and JSONL layers land the delegation surfaces the full spec set ("NoCredentials", "SubprocessFailed", "IoError", "ParseError", etc.).

Trait Implementations

impl Debug for UsageError

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

Formats the value using the given formatter.

impl Display for UsageError

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

Formats the value using the given formatter.

impl Error for UsageError

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.