Errors

Error Response Format

All errors return JSON:

{
  "code": "USER_NOT_FOUND",
  "message": "User not found"
}

code is present only when the upstream TypeScript implementation defines a constant for that message; the table mirrors every defineErrorCodes entry in better-auth and its plugins. Messages without an upstream code carry only message, so clients should branch on code when it exists and fall back to the status otherwise.

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
`Redis`	500	Redis operation failed; available with `redis-cache`

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);
        }
    }
}

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
`BadRequest("Challenge not found")`	Missing or invalid passkey challenge cookie
`BadRequest("Authentication failed")`	Invalid passkey assertion
`Forbidden("Passkey not found")`	Passkey credential does not exist

Error Handling in Axum

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

use axum::Json;
use better_auth::error::AuthError;

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

Errors

On this page