Quickstart

Get started with Convex Rate Limiter in minutes

This guide walks you through setting up and using the Convex Rate Limiter component with real examples.

1. Install the Package

   First, install the rate limiter component:

   npm

   npm install @convex-dev/rate-limiter
   
2. Configure convex.config.ts

   Create or update convex/convex.config.ts to register the component:

   convex/convex.config.ts

   import { defineApp } from "convex/server";
   import rateLimiter from "@convex-dev/rate-limiter/convex.config.js";
   
   const app = defineApp();
   app.use(rateLimiter);
   
   export default app;
   
3. Define Your Rate Limits

   Create a new file (e.g., convex/rateLimits.ts) and define your rate limits:

   convex/rateLimits.ts

   import { RateLimiter, MINUTE, HOUR } from "@convex-dev/rate-limiter";
   import { components } from "./_generated/api";
   
   export const rateLimiter = new RateLimiter(components.rateLimiter, {
     // A per-user limit, allowing one every ~6 seconds.
     // Allows up to 3 in quick succession if they haven't sent many recently.
     sendMessage: { kind: "token bucket", rate: 10, period: MINUTE, capacity: 3 },
     
     // One global / singleton rate limit for free trial signups
     freeTrialSignUp: { kind: "fixed window", rate: 100, period: HOUR },
   });
   

   Rate limit strategies:

   • Token bucket: Tokens are added at a steady rate, allowing bursts up to capacity
   • Fixed window: All tokens granted at once every period, with optional rollover
4. Use in a Mutation - Global Rate Limit

   Apply a global rate limit that applies to all users:

   convex/users.ts

   import { mutation } from "./_generated/server";
   import { rateLimiter } from "./rateLimits";
   
   export const signUpForFreeTrial = mutation({
     args: { /* ... */ },
     handler: async (ctx, args) => {
       // Check global rate limit for free trial signups
       const { ok, retryAfter } = await rateLimiter.limit(ctx, "freeTrialSignUp");
       
       if (!ok) {
         throw new Error(
           `Rate limit exceeded. Please try again in ${Math.ceil(retryAfter! / 1000)} seconds.`
         );
       }
       
       // Proceed with signup logic...
     },
   });
   
5. Use in a Mutation - Per-User Rate Limit

   Apply a rate limit specific to each user using a key:

   convex/messages.ts

   import { mutation } from "./_generated/server";
   import { v } from "convex/values";
   import { rateLimiter } from "./rateLimits";
   
   export const sendMessage = mutation({
     args: {
       text: v.string(),
     },
     handler: async (ctx, args) => {
       const user = await ctx.auth.getUserIdentity();
       if (!user) {
         throw new Error("Not authenticated");
       }
       
       // Rate limit per user
       const { ok, retryAfter } = await rateLimiter.limit(ctx, "sendMessage", {
         key: user.subject,
       });
       
       if (!ok) {
         throw new Error(
           `You're sending messages too quickly. Please wait ${Math.ceil(retryAfter! / 1000)} seconds.`
         );
       }
       
       // Save the message
       await ctx.db.insert("messages", {
         text: args.text,
         userId: user.subject,
         timestamp: Date.now(),
       });
     },
   });
   
6. Error Handling with throws Option

   For cleaner code, use the throws option to automatically throw errors when rate limits are exceeded:

   convex/auth.ts

   import { mutation } from "./_generated/server";
   import { v } from "convex/values";
   import { RateLimiter, HOUR, isRateLimitError } from "@convex-dev/rate-limiter";
   import { components } from "./_generated/api";
   
   const rateLimiter = new RateLimiter(components.rateLimiter, {
     failedLogins: { kind: "token bucket", rate: 10, period: HOUR },
   });
   
   export const login = mutation({
     args: {
       email: v.string(),
       password: v.string(),
     },
     handler: async (ctx, args) => {
       try {
         // Automatically throw if rate limit is exceeded
         await rateLimiter.limit(ctx, "failedLogins", {
           key: args.email,
           throws: true,
         });
         
         // Attempt login...
         const success = await attemptLogin(args.email, args.password);
         
         if (success) {
           // Reset rate limit on successful login
           await rateLimiter.reset(ctx, "failedLogins", { key: args.email });
         }
         
         return { success };
       } catch (error) {
         if (isRateLimitError(error)) {
           throw new Error(
             `Too many failed login attempts. Please try again later.`
           );
         }
         throw error;
       }
     },
   });
   
   function attemptLogin(email: string, password: string) {
     // Your login logic here
     return true;
   }
   

   When using throws: true, the rate limiter throws a ConvexError with data {kind: "RateLimited", name, retryAfter}. Use isRateLimitError() to check if an error is a rate limit error.

What You’ve Learned

You now know how to:

• Install and configure the Convex Rate Limiter component
• Define rate limits with different strategies (token bucket and fixed window)
• Apply global rate limits that affect all users
• Apply per-user rate limits using keys
• Handle rate limit errors gracefully
• Reset rate limits when needed

Next Steps

Explore more advanced features:

• Custom token counts: Consume multiple tokens in a single request for LLM token limiting
• Sharding: Scale to high throughput with configurable sharding
• Reservations: Reserve capacity to avoid starvation on larger requests
• React hook: Check rate limits from your frontend with useRateLimit

For detailed information, check out the full Stack post on rate limiting.