Enum AuthError 

pub enum AuthError {
    SchemaCheck(Arc<SchemaCheckError>),
    Response(ApiErrorResponse),
    FieldInput {
        code: &'static str,
        message: String,
    },
    Upstream {
        status: u16,
        code: &'static str,
        message: &'static str,
    },
    BadRequest(String),
    InvalidRequest(String),
    Validation(String),
    InvalidCredentials,
    Unauthenticated,
    AuthenticationFailed(String),
    SessionNotFound,
    Forbidden(String),
    BannedUser(String),
    Unauthorized,
    UserNotFound,
    NotFound(String),
    Conflict(String),
    MethodNotAllowed(String),
    PayloadTooLarge(String),
    UnprocessableEntity(String),
    RateLimited,
    NotImplemented(String),
    Config(String),
    Database(DatabaseError),
    Serialization(Error),
    Plugin {
        plugin: String,
        message: String,
    },
    Internal(String),
    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

SchemaCheck(Arc<SchemaCheckError>)

Runtime schema failures reject the host entry point before endpoint error handling.

Response(ApiErrorResponse)

Preserve an endpoint’s complete error body and repeated response headers.

FieldInput

Public schema error with a field-specific message.

Fields

code: &'static str

Upstream schema error code.

message: String

Validation message safe to return to the caller.

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)

BannedUser(String)

Unauthorized

UserNotFound

NotFound(String)

Conflict(String)

MethodNotAllowed(String)

PayloadTooLarge(String)

UnprocessableEntity(String)

RateLimited

NotImplemented(String)

Config(String)

Database(DatabaseError)

Serialization(Error)

Plugin

Fields

plugin: String

message: String

Internal(String)

PasswordHash(String)

Jwt(Error)

Implementations

impl AuthError

pub fn instrumentation_message(&self) -> String

Diagnostic message for tracing. Response headers are never included.

pub fn redirect(location: impl Into<String>) -> Self

Create a redirect that bypasses the HTTP error callback, like upstream FOUND. Numeric 302 errors created from AuthResponse retain the ordinary API error policy.

pub fn is_found_redirect(&self) -> bool

Whether this error is an explicit FOUND redirect.

pub fn capture_endpoint_headers(self, headers: Headers) -> Self

Attach endpoint headers while preserving the redirect’s error-policy behavior.

pub fn is_api_error(&self) -> bool

Whether the error is an intentional endpoint rejection, including redirects and server API errors.

pub fn to_http_response(self) -> AuthResponse

Serialize an HTTP endpoint failure without exposing ordinary runtime errors.

pub 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 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 SchemaCheckError

fn from(source: AuthError) -> Self

Converts to this type from the input type.

impl From<AuthResponse> for AuthError

fn from(response: AuthResponse) -> 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.