Enum AuthError 

pub enum AuthError {
    Api {
        status: u16,
        code: Option<String>,
        message: String,
    },
    Upstream {
        status: u16,
        code: &'static str,
        message: &'static str,
    },
    BadRequest(String),
    InvalidRequest(String),
    Validation(String),
    InvalidCredentials,
    Unauthenticated,
    AuthenticationFailed(String),
    SessionNotFound,
    Forbidden(String),
    SessionCreationCancelled,
    UserCreationCancelled,
    BannedUser(String),
    Unauthorized,
    UserNotFound,
    NotFound(String),
    Conflict(String),
    MethodNotAllowed(String),
    PayloadTooLarge(String),
    UnprocessableEntity(String),
    RateLimited {
        retry_after: Option<f64>,
    },
    NotImplemented(String),
    Config(String),
    Database(DatabaseError),
    Serialization(Error),
    Plugin {
        plugin: String,
        message: String,
    },
    Internal(String),
    Encryption(String),
    CallbackFailure(Box<Self>),
    PasswordHash(String),
    Jwt(Error),
}

Authentication framework error types.

Each variant maps to an HTTP status code via AuthError::status_code. Use AuthError::to_auth_response to produce a standardized JSON response matching the better-auth OpenAPI spec: { "message": "..." }.

Variants

Api

An intentional public API error from application policy or input validation.

The supplied message is returned verbatim, including for a 500 status. Use internal error variants for database failures or other private details.

Fields

status: u16

code: Option<String>

message: String

Upstream

A documented upstream API error whose message is safe to return publicly.

Fields

status: u16

HTTP response status defined by the upstream endpoint.

code: &'static str

Stable upstream error code.

message: &'static str

Documented public error message. Never include internal failure details.

BadRequest(String)

InvalidRequest(String)

Validation(String)

InvalidCredentials

Unauthenticated

AuthenticationFailed(String)

SessionNotFound

Forbidden(String)

SessionCreationCancelled

A session-create lifecycle hook explicitly cancelled creation. Callers may apply endpoint-specific null-session behavior; the default public response retains the existing cancellation status and message.

UserCreationCancelled

A user-create database hook explicitly cancelled creation. Endpoint owners may map the absent user differently from a genuine application Forbidden error with the same text.

BannedUser(String)

Unauthorized

UserNotFound

NotFound(String)

Conflict(String)

MethodNotAllowed(String)

PayloadTooLarge(String)

UnprocessableEntity(String)

RateLimited

retry_after is the number of seconds until the next request is admitted; responses publish it as X-Retry-After.

Fields

retry_after: Option<f64>

NotImplemented(String)

Config(String)

Database(DatabaseError)

Serialization(Error)

Plugin

Fields

plugin: String

message: String

Internal(String)

Encryption(String)

Authentication or encoding of encrypted persistence data failed. HTTP callers receive an empty 500; private details are logged.

CallbackFailure(Box<Self>)

An ordinary application callback failure whose HTTP contract is an empty 500. The private cause is logged, never sent to the client. Explicit API errors retain their own response and must not be wrapped in this variant.

PasswordHash(String)

Jwt(Error)

Implementations

impl AuthError

pub const fn status_code(&self) -> u16

HTTP status code for this error.

pub fn code_from_message(message: &str) -> Option<String>

Resolve the wire error code for a message, if upstream defines one.

better-auth 1.5 replaced message-derived codes with explicit constants, and only errors built from one of those constants carry a code at all (APIError.from sets it; a plain new APIError(status, { message }) does not). So an unknown message yields None and the field is omitted, rather than being back-derived from the text.

pub fn error_payload(&self) -> (u16, Option<String>, String)

Compute the HTTP status, error code, and user-facing message.

The code is None for messages upstream has no constant for; those responses carry only a message.

Internal errors (500) are logged and replaced with a generic message to avoid leaking details.

pub fn to_auth_response(self) -> AuthResponse

Convert this error into a standardized AuthResponse matching the better-auth spec: { "code": "...", "message": "..." }.

Named to_auth_response to avoid collision with Axum’s IntoResponse::into_response when the axum feature is enabled.

pub const fn rate_limited(retry_after: f64) -> Self

A 429 rejection that tells the client to retry after retry_after seconds, such as RateLimitDecision::Blocked’s.

pub fn bad_request(message: impl Into<String>) -> Self

pub fn forbidden(message: impl Into<String>) -> Self

pub fn banned_user(message: impl Into<String>) -> Self

pub fn not_found(message: impl Into<String>) -> Self

pub fn conflict(message: impl Into<String>) -> Self

pub fn method_not_allowed(message: impl Into<String>) -> Self

pub fn payload_too_large(message: impl Into<String>) -> Self

pub fn not_implemented(message: impl Into<String>) -> Self

pub fn plugin(plugin: &str, message: impl Into<String>) -> Self

pub fn config(message: impl Into<String>) -> Self

pub fn internal(message: impl Into<String>) -> Self

pub fn validation(message: impl Into<String>) -> Self

pub fn authentication_failed(message: impl Into<String>) -> Self

Trait Implementations

impl Debug for AuthError

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

Formats the value using the given formatter.

impl Display for AuthError

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

Formats the value using the given formatter.

impl Error for AuthError

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<AuthError> for EndpointError

fn from(error: AuthError) -> Self

Converts to this type from the input type.

impl From<DatabaseError> for AuthError

fn from(source: DatabaseError) -> Self

Converts to this type from the input type.

impl From<Error> for AuthError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for AuthError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl IntoResponse for AuthError

Available on crate feature axum only.

fn into_response(self) -> Response

Create a response.