Rate Limit

Better Auth includes a built-in rate limiter to help manage traffic and prevent abuse. By default, in production mode, the rate limiter is set to:

Window: 60 seconds
Max Requests: 100 requests

You can easily customize these settings by passing the rateLimit object to the betterAuth function.

auth.ts

import { betterAuth } from "better-auth";
 
export const auth = betterAuth({
    rateLimit: {
        window: 10, // time window in seconds
        max: 100, // max requests in the window
    },
})

In addition to the default settings, Better Auth provides custom rules for specific paths. For example:

/sign-in/email: Is limited to 3 requests within 10 seconds.

In addition, plugins also define custom rules for specific paths. For example, twoFactor plugin has custom rules:

/two-factor/verify: Is limited to 3 requests within 10 seconds.

These custom rules ensure that sensitive operations are protected with stricter limits.

Configuring Rate Limit

Rate Limit Window

auth.ts

import { betterAuth } from "better-auth";
 
export const auth = betterAuth({
    //...other options
    rateLimit: {
        window: 60, // time window in seconds
        max: 100, // max requests in the window
    },
})

You can also pass custom rules for specific paths.

auth.ts

import { betterAuth } from "better-auth";
 
export const auth = betterAuth({
    //...other options
    rateLimit: {
        window: 60, // time window in seconds
        max: 100, // max requests in the window
        customRules: {
            "/sign-in/email": {
                window: 10,
                max: 3,
            },
            "/two-factor/*": async (request)=> {
                // custom function to return rate limit window and max
                return {
                    window: 10,
                    max: 3,
                }
            }
        },
    },
})

By default, rate limit data is stored in memory, which may not be suitable for many use cases, particularly in serverless environments. To address this, you can use a database, secondary storage, or custom storage for storing rate limit data.

Using Database

auth.ts

import { betterAuth } from "better-auth";
 
export const auth = betterAuth({
    //...other options
    rateLimit: {
        storage: "database",
        modelName: "rateLimit", //optional by default "rateLimit" is used
    },
})

Make sure to run migrate to create the rate limit table in your database.

npx @better-auth/cli migrate

Using Secondary Storage

If a Secondary Storage has been configured you can use that to store rate limit data.

auth.ts

import { betterAuth } from "better-auth";
 
export const auth = betterAuth({
    //...other options
    rateLimit: {
		storage: "secondary-storage"
    },
})

Custom Storage

If none of the above solutions suits your use case you can implement a customStorage.

auth.ts

import { betterAuth } from "better-auth";
 
export const auth = betterAuth({
    //...other options
    rateLimit: {
        customStorage: {
            get: async (key) => {
                // get rate limit data
            },
            set: async (key, value) => {
                // set rate limit data
            },
        },
    },
})

Handling Rate Limit Errors

When a request exceeds the rate limit, Better Auth returns the following header:

X-Retry-After: The number of seconds until the user can make another request.

To handle rate limit errors on the client side, you can manage them either globally or on a per-request basis. Since Better Auth clients wrap over Better Fetch, you can pass fetchOptions to handle rate limit errors

Global Handling

auth-client.ts

import { createAuthClient } from "better-auth/client";
 
export const authClient =  createAuthClient({
    fetchOptions: {
        onError: async (context) => {
            const { response } = context;
            if (response.status === 429) {
                const retryAfter = response.headers.get("X-Retry-After");
                console.log(`Rate limit exceeded. Retry after ${retryAfter} seconds`);
            }
        },
    }
})

Per Request Handling

auth-client.ts

import { client } from "./client";
 
await authClient.signIn.email({
    fetchOptions: {
        onError: async (context) => {
            const { response } = context;
            if (response.status === 429) {
                const retryAfter = response.headers.get("X-Retry-After");
                console.log(`Rate limit exceeded. Retry after ${retryAfter} seconds`);
            }
        },
    }
})

Schema

If you are using a database to store rate limit data you need this schema:

Table Name: rateLimit

Field Name	Type	Key	Description
key	string		Unique identifier for each rate limit key
count	integer	-	Time window in seconds
lastRequest	bigint	-	Max requests in the window

OAuth

How Better Auth handles OAuth

Session Management

Better Auth session management.

Configuring Rate Limit

Rate Limit Window

Storage

Handling Rate Limit Errors

Schema

OAuth

Session Management

On this page