Enum OAuthError 

pub enum OAuthError {
    Config(String),
    Discovery(String),
    TokenExchange(String),
    IdTokenValidation(String),
    UnknownProvider(String),
    CsrfMismatch,
    NoFlow,
    Expired,
    InvalidParameter,
    RefreshTokenExpired,
    NoRefreshToken,
    NoAccessToken,
    UserInfo(String),
    AccessTokenExpired,
    InsufficientScope,
    DeviceAuthorization(String),
    UnknownKid(String),
    UnsupportedTokenType,
    TokenEndpointTransient {
        status: u16,
        body: String,
    },
}

Available on crate feature oauth only.

Errors returned by OAuth 2.0 / OIDC operations across discovery, token exchange, ID-token validation, and refresh.

Variants

Config(String)

Provider configuration is missing required fields or fails validation.

Discovery(String)

Failure fetching or parsing the OIDC discovery document.

TokenExchange(String)

Token endpoint rejected the authorization code or returned an unparseable response.

IdTokenValidation(String)

ID token failed signature, issuer, audience, or claim-set validation.

UnknownProvider(String)

No provider is registered under the requested name.

CsrfMismatch

state returned by the IdP did not match the value stored at flow start.

NoFlow

Callback received but no in-progress flow was found in the session.

Expired

In-progress flow exceeded its TTL before the user completed the IdP redirect.

InvalidParameter

Required callback parameter is missing or malformed.

RefreshTokenExpired

IdP rejected the refresh token (RFC 6749 invalid_grant).

NoRefreshToken

Operation requires a refresh token but none is stored for this session.

NoAccessToken

Operation requires an access token but none is stored for this session.

UserInfo(String)

UserInfo endpoint call failed.

AccessTokenExpired

Access token expired or was rejected by the resource server.

InsufficientScope

Stored access token lacks the scopes required to call UserInfo.

DeviceAuthorization(String)

RFC 8628 device authorization endpoint returned an error.

UnknownKid(String)

JWT verification failed because the kid is not present in the cached JWKS. Callers (e.g. back-channel logout) match on this variant to trigger a refresh_jwks() + retry, instead of fragile substring-matching the error message.

UnsupportedTokenType

RFC 7009 §2.2.1: the authorization server received the revocation request but does not support the supplied token type (e.g. it can revoke refresh_token but not access_token). Callers should usually log + ignore: a token the AS cannot revoke is, from its perspective, already “not a valid token”.

TokenEndpointTransient

A server-side (5xx) failure from a token endpoint (revocation / refresh / exchange). Distinct from TokenExchange so callers can distinguish “AS rejected our request” from “AS is broken right now and a retry might succeed”.

Fields

status: u16

HTTP status code returned by the AS (5xx range).

body: String

Body of the failed response (truncated upstream if large).

Implementations

impl OAuthError

pub fn is_transient(&self) -> bool

Hint at whether this error is worth retrying.

Returns true for failures the application can reasonably retry: 5xx token-endpoint responses, network-shaped discovery failures, network-shaped userinfo failures. Returns false for permanent semantic rejections (CSRF mismatch, expired ceremony, invalid parameters, unknown provider, unsupported token type).

The classification is conservative: anything that might be a permanent state error returns false. Callers building retry loops should still apply per-call backoff and a hard attempt cap; this is a hint, not an exponential-backoff oracle.

Config(_), IdTokenValidation(_), and UnknownKid(_) are not transient: they indicate misconfiguration or a key rotation that requires refresh_jwks() first, not a blind retry of the same call.

Consumer pattern: retry with capped exponential backoff

is_transient() is the only contract; the caller owns the backoff schedule, attempt cap, and any jitter. The pattern below is what axess expects consumers to implement around any call that can return OAuthError:

use std::time::Duration;
use axess_factors::oauth::OAuthError;

async fn with_retry<T, F, Fut>(mut op: F) -> Result<T, OAuthError>
where
    F: FnMut() -> Fut,
    Fut: std::future::Future<Output = Result<T, OAuthError>>,
{
    const MAX_ATTEMPTS: u32 = 4;
    let mut delay = Duration::from_millis(250);
    for attempt in 1..=MAX_ATTEMPTS {
        match op().await {
            Ok(v) => return Ok(v),
            Err(e) if e.is_transient() && attempt < MAX_ATTEMPTS => {
                tokio::time::sleep(delay).await;
                delay = delay.saturating_mul(2); // 250ms, 500ms, 1s
            }
            Err(e) => return Err(e), // permanent OR cap exhausted
        }
    }
    unreachable!() // loop body always returns
}

Do not retry indefinitely. A permanent error like CsrfMismatch or Expired returns false so the loop exits immediately, but a transient classification on a misbehaving upstream can otherwise spin forever. Always cap attempts and emit a tracing::warn! on each backoff so SOC dashboards see the upstream degradation.

Trait Implementations

impl Debug for OAuthError

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

Formats the value using the given formatter.

impl Display for OAuthError

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

Formats the value using the given formatter.

impl Error for OAuthError

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.