Enum AuthnError 

pub enum AuthnError<E: Error + Send + Sync + 'static> {
    Store(E),
    NoFlow,
    NotActive(EntityState),
    Locked {
        until: Option<DateTime<Utc>>,
    },
    InvalidAssertion,
    ExternalService(String),
    CrossTenant,
}

Errors that can occur during authentication flows.

Parameterised over the backend error type E so that storage errors are propagated with their original type rather than being erased.

Suggested HTTP status code mapping

Variant	HTTP Status	Rationale
Store	500 Internal Server Error	Backend / database failure; not the client’s fault.
NoFlow	409 Conflict	No active authentication flow in the session; client must start one first.
NotActive	403 Forbidden	Account exists but is disabled, suspended, or otherwise ineligible.
Locked	423 Locked	Account locked due to too many failed attempts; retry after cooldown.
InvalidAssertion	401 Unauthorized	FIDO2 cryptographic validation failed; credential rejected.
ExternalService	502 Bad Gateway	Upstream provider (LDAP, OAuth IdP) returned an error or timed out.

These are suggestions for handler authors. The library does not convert errors to HTTP responses automatically; that mapping belongs in your application’s error-handling layer.

Variants

Store(E)

An error from the underlying identity or factor store.

NoFlow

No active authentication flow found in the session.

Returned by verify_factor when the session is not in Authenticating state.

NotActive(EntityState)

The account exists but is not in a state that permits login.

Locked

The account is locked (suspension or accumulated failed attempts).

Returned by:

• prepare_factor when account_status reports Suspended.
• FIDO2 finish_discoverable_login when the lockout threshold is reached during a discoverable assertion’s failure path.

until is the suspension expiry when known (for Suspended accounts whose StatusDetail.until is set), None for indefinite locks or for the failed-attempt lockout (which has no inherent expiry: an admin must reset). Use lockout_expiry for one-call access that also handles the legacy NotActive(EntityState::Suspended(_)) case.

Callers should display a generic “account locked” message (rendering until if present and non-trivial) rather than distinguishing failed-attempt vs admin-suspension reasons; that distinction is operator-visible via the audit log, never a property of the error response.

Fields

until: Option<DateTime<Utc>>

Wall-clock expiry of the lock, when known.

InvalidAssertion

A FIDO2/WebAuthn assertion or registration failed validation.

Distinct from NoFlow (no ceremony in progress): this means a ceremony was in progress but the cryptographic validation failed.

ExternalService(String)

An external service (LDAP, OAuth IdP, etc.) failed with a non-credential error (connection timeout, network issue, etc.).

Callers should treat this as a transient failure and may retry or show a “service unavailable” message, not “invalid credentials”.

CrossTenant

A tenant-scoped operation was invoked against a target whose tenant_id does not match the caller-supplied expected tenant.

Returned by the _in_tenant family of methods on AuthnService (e.g. suspend_user_in_tenant, activate_user_in_tenant, begin_impersonation_in_tenant) when the structural rail fires. Suggested HTTP status: 403 Forbidden (the caller is authenticated but operating outside their authorised scope).

Treat audit logging of this variant as security-relevant; it almost always indicates either a buggy admin UI or an attempted cross-tenant pivot.

Implementations

impl<E: Error + Send + Sync + 'static> AuthnError<E>

pub fn lockout_expiry(&self) -> Option<DateTime<Utc>>

Return the lockout expiry timestamp when this error represents a locked account, regardless of whether the lock surfaces as AuthnError::Locked or as AuthnError::NotActive(EntityState::Suspended(_)).

Returns None for indefinite locks, for failed-attempt lockouts (which have no inherent expiry), and for any non-lock error variant. Use this from UI code that wants to render “try again at X” without distinguishing the two error shapes: both a prepare_factor Suspended-account rejection and a FIDO2 discoverable-login lockout collapse to a single Option<DateTime<Utc>> lookup.

Saves callers from deep-pattern-matching EntityState::Suspended(StatusDetail { until, .. }) and handling the AuthnError::Locked { until } shape separately; both legs collapse to one call.

impl<E: Error + Send + Sync + 'static> AuthnError<E>

Default IntoResponse mapping for AuthnError.

Gated behind the default-error-response feature because mapping a library error to an HTTP response is policy that belongs to the application: status code, body shape, locale, correlation IDs, and problem+json formatting are all things callers may want to override. The doc table on AuthnError documents the recommended mapping for applications that ship their own impl.

Enable with axess-core = { features = ["default-error-response"] } to get the conservative default below.

pub fn into_response_at(self, now: DateTime<Utc>) -> Response

Available on crate feature default-error-response only.

IntoResponse-shaped conversion taking the reference time explicitly. Test code with MockClock uses this to pin the Retry-After header against a controllable clock; the trait impl below delegates here with Utc::now() for production callers, which produces wall-clock behaviour that’s correct but non-deterministic across runs.

Adopters who don’t enable the default-error-response feature can still construct their own IntoResponse impl on top of this helper without forking the body/status logic.

Trait Implementations

impl<E: Debug + Error + Send + Sync + 'static> Debug for AuthnError<E>

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

Formats the value using the given formatter.

impl<E> Display for AuthnError<E>

where E: Display + Error + Send + Sync + 'static,

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

Formats the value using the given formatter.

impl<E> Error for AuthnError<E>

where E: Error + 'static + Error + Send + Sync, Self: Debug + Display,

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<E: Error + Send + Sync + 'static> IntoResponse for AuthnError<E>

Available on crate feature default-error-response only.

fn into_response(self) -> Response

Delegates to AuthnError::into_response_at with chrono::Utc::now() as the reference time. Production-correct but non-deterministic; tests asserting on Retry-After should call into_response_at directly with a MockClock-derived timestamp.