Errors

Error Response Format

All errors return JSON:

{
  "message": "Description of the error"
}

For 5xx errors, the actual error details are hidden and a generic message is returned to avoid leaking internal information.

AuthError Variants

Variant	HTTP Status	Description
`BadRequest`	400	Malformed request
`InvalidRequest`	400	Invalid request parameters
`Validation`	400	Input validation failed
`InvalidCredentials`	401	Wrong email/password
`Unauthenticated`	401	No valid session token
`SessionNotFound`	401	Session token not found or expired
`Forbidden`	403	Action not allowed
`Unauthorized`	403	Insufficient permissions
`UserNotFound`	404	User does not exist
`NotFound`	404	Resource not found
`Conflict`	409	Duplicate resource (email, username)
`RateLimited`	429	Too many requests
`NotImplemented`	501	Feature not implemented
`Config`	500	Configuration error
`Database`	500	Database operation failed
`Serialization`	500	JSON serialization error
`Plugin`	500	Plugin-specific error
`Internal`	500	Unexpected internal error
`PasswordHash`	500	Password hashing failure
`Jwt`	500	JWT encoding/decoding error

DatabaseError Variants

Database errors are wrapped in AuthError::Database:

Variant	Description
`Connection`	Failed to connect to database
`Query`	Query execution failed
`Migration`	Migration failed
`Constraint`	Unique constraint violation
`Transaction`	Transaction failed

Programmatic Error Handling

use better_auth::error::{AuthError, AuthResult};

fn handle_result(result: AuthResult<()>) {
    match result {
        Ok(()) => println!("Success"),
        Err(e) => {
            println!("Status: {}", e.status_code());
            println!("Message: {}", e.message());
        }
    }
}

Constructors for common errors:

AuthError::bad_request("Invalid input");
AuthError::forbidden("Not allowed");
AuthError::not_found("User not found");
AuthError::conflict("Email already exists");
AuthError::internal("Unexpected error");
AuthError::validation("Password too short");
AuthError::plugin("my-plugin", "Something went wrong");
AuthError::not_implemented("Feature not available yet");

Common Error Scenarios

Authentication Errors

Error	When	Resolution
`Unauthenticated`	Missing or invalid session token	Include a valid `Authorization: Bearer <token>` header or session cookie
`InvalidCredentials`	Wrong email/password combination	Check credentials and retry
`SessionNotFound`	Expired or revoked session	Re-authenticate to get a new session

Authorization Errors

Error	When	Resolution
`Forbidden`	User lacks required role (e.g., admin)	Ensure the user has the appropriate role
`Unauthorized`	Insufficient RBAC permissions	Check organization role and permissions

Validation Errors

Error	When	Resolution
`Validation`	Request body fails validation	Check required fields, formats, and constraints
`BadRequest`	Malformed or missing request data	Ensure the request matches the expected format

Resource Errors

Error	When	Resolution
`UserNotFound`	Referenced user doesn't exist	Verify the user ID
`NotFound`	Resource (org, member, key, etc.) not found	Check the resource ID and ownership
`Conflict`	Email, username, or slug already exists	Use a different value

Rate Limiting

Error	When	Resolution
`RateLimited`	Too many requests in the time window	Wait for `retryAfter` seconds before retrying

Plugin-Specific Errors

OAuth Plugin

Error	When
`BadRequest("Unknown provider")`	Provider name not registered
`BadRequest("Missing code parameter")`	OAuth callback missing authorization code
`BadRequest("Provider mismatch")`	State provider doesn't match callback provider
`Conflict("Social account already linked")`	Provider account linked to another user

Two-Factor Plugin

Error	When
`NotFound("Two-factor authentication not enabled")`	2FA not set up for user
`BadRequest("Invalid backup code")`	Backup code doesn't match
`BadRequest("No backup codes available")`	All backup codes used

Organization Plugin

Error	When
`Forbidden("Insufficient permissions")`	Role lacks required RBAC permission
`Conflict("Slug already taken")`	Organization slug already in use

Passkey Plugin

Error	When
`NotImplemented(...)`	`allow_insecure_unverified_assertion` is `false`
`BadRequest("Invalid or expired ... challenge")`	Challenge expired or already used

Error Handling in Axum

When using the Axum integration, AuthError is automatically converted to an HTTP response:

use axum::{Json, response::IntoResponse};
use better_auth::error::AuthError;

async fn my_handler() -> Result<impl IntoResponse, AuthError> {
    // AuthError automatically becomes the right HTTP status + JSON body
    Err(AuthError::bad_request("Something went wrong"))
}

Errors

On this page