Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/get-convex/rate-limiter/llms.txt

Use this file to discover all available pages before exploring further.

This page documents all exported TypeScript types for the Convex Rate Limiter.

​
RateLimitConfig

A union type representing the configuration for a rate limit. Can be either a token bucket or fixed window configuration. 
type RateLimitConfig =
  | Infer<typeof tokenBucketValidator>
  | Infer<typeof fixedWindowValidator>;

​
Token Bucket Configuration

A token bucket limits the rate of requests by continuously adding tokens to be consumed when servicing requests. 
{
  kind: "token bucket",
  rate: number,
  period: number,
  capacity?: number,
  maxReserved?: number,
  shards?: number,
  start?: null
}
Example: 
const config: RateLimitConfig = {
  kind: "token bucket",
  rate: 10,
  period: MINUTE,
  capacity: 20
};

​
Fixed Window Configuration

A fixed window rate limit adds a set number of tokens at the start of each fixed window of time. 
{
  kind: "fixed window",
  rate: number,
  period: number,
  capacity?: number,
  maxReserved?: number,
  shards?: number,
  start?: number
}
Example: 
const config: RateLimitConfig = {
  kind: "fixed window",
  rate: 100,
  period: HOUR,
  start: 0
};

​
RateLimitArgs

Arguments for rate limiting operations. 
type RateLimitArgs = {
  /** The name of the rate limit. */
  name: string;
  /** The key to use for the rate limit. If not provided, the rate limit
   * is a single shared value.  */
  key?: string;
  /**  The number of tokens to consume. Defaults to 1. */
  count?: number;
  /**  Whether to reserve the tokens ahead of time. Defaults to false. */
  reserve?: boolean;
  /**  Whether to throw an error if the rate limit is exceeded.
   * By default, check/consume will just return { ok: false, retryAfter: number }.
   */
  throws?: boolean;
  /** The rate limit configuration. See {@link RateLimitConfig}. */
  config: RateLimitConfig;
};
Example: 
const args: RateLimitArgs = {
  name: "sendMessage",
  key: userId,
  count: 1,
  throws: true,
  config: {
    kind: "token bucket",
    rate: 10,
    period: MINUTE
  }
};

​
RateLimitReturns

Return value from rate limiting operations. 
type RateLimitReturns = 
  | {
      ok: true,
      retryAfter?: number
    }
  | {
      ok: false,
      retryAfter: number
    };
Example: 
const result = await rateLimiter.limit(ctx, "sendMessage", { key: userId });

if (result.ok) {
  // Request allowed
  if (result.retryAfter) {
    // For reserved tokens, schedule work
    await ctx.scheduler.runAfter(result.retryAfter, internal.sendMessage, {...});
  }
} else {
  // Rate limited - retry after result.retryAfter ms
  console.log(`Rate limited. Retry after ${result.retryAfter}ms`);
}

​
RateLimitError

Error type thrown when throws: true is used and the rate limit is exceeded. 
type RateLimitError = {
  kind: "RateLimited";
  name: string;
  retryAfter: number;
};
​
kind
literal
required
Always "RateLimited" to identify this error type
​
name
string
required
The name of the rate limit that was exceeded
​
retryAfter
number
required
Duration in milliseconds when retrying could succeed
Example: 
import { isRateLimitError } from "@convex-dev/rate-limiter";

try {
  await rateLimiter.limit(ctx, "sendMessage", { 
    key: userId, 
    throws: true 
  });
} catch (error) {
  if (isRateLimitError(error)) {
    console.log(`Rate limited on ${error.data.name}`);
    console.log(`Retry after ${error.data.retryAfter}ms`);
  }
}

​
GetValueArgs

Arguments for getting the current value of a rate limit. 
type GetValueArgs = {
  name?: string;
  key?: string;
  sampleShards?: number;
  config?: RateLimitConfig;
};
​
name
string
The name of the rate limit
​
key
string
The key to check. If not provided, checks the shared value.
​
sampleShards
number
The number of shards to sample when checking the value
​
config
RateLimitConfig
The rate limit configuration if not using a pre-defined limit
Example: 
const value = await rateLimiter.getValue(ctx, "sendMessage", {
  key: userId,
  sampleShards: 1
});

​
GetValueReturns

Return value from getting the current rate limit value. 
type GetValueReturns = {
  value: number;
  ts: number;
  shard: number;
  config: RateLimitConfig;
};
​
value
number
required
The current number of available tokens
​
ts
number
required
The timestamp of the last update (in milliseconds)
​
shard
number
required
The shard number that was sampled
​
config
RateLimitConfig
required
The rate limit configuration
Example: 
const { value, ts, shard, config } = await rateLimiter.getValue(
  ctx, 
  "sendMessage", 
  { key: userId }
);

console.log(`${value} tokens available at ${new Date(ts)}`);

​
Validators

Convex validators for rate limit configurations.

​
tokenBucketValidator

const tokenBucketValidator = v.object({
  kind: v.literal("token bucket"),
  rate: v.number(),
  period: v.number(),
  capacity: v.optional(v.number()),
  maxReserved: v.optional(v.number()),
  shards: v.optional(v.number()),
  start: v.optional(v.null()),
});
Convex validator for token bucket configurations. Use with Infer<typeof tokenBucketValidator> to get the TypeScript type.

​
fixedWindowValidator

const fixedWindowValidator = v.object({
  kind: v.literal("fixed window"),
  rate: v.number(),
  period: v.number(),
  capacity: v.optional(v.number()),
  maxReserved: v.optional(v.number()),
  shards: v.optional(v.number()),
  start: v.optional(v.number()),
});
Convex validator for fixed window configurations. Use with Infer<typeof fixedWindowValidator> to get the TypeScript type.

​
Context Types

Context types used by the RateLimiter methods to specify which Convex operations are available.

​
RunQueryCtx

A context that provides access to runQuery. Used by non-mutating operations like check() and getValue(). 
type RunQueryCtx = {
  runQuery: <Query extends FunctionReference<"query", "internal">>(
    query: Query,
    args: FunctionArgs<Query>,
  ) => Promise<FunctionReturnType<Query>>;
};
Example: 
// Any Convex query or mutation context works
export const checkLimit = query({
  handler: async (ctx, args) => {
    // ctx implements RunQueryCtx
    const status = await rateLimiter.check(ctx, "myLimit");
    return status;
  }
});

​
RunMutationCtx

A context that extends RunQueryCtx and provides access to both runQuery and runMutation. Used by mutating operations like limit() and reset(). 
type RunMutationCtx = RunQueryCtx & {
  runMutation: <Mutation extends FunctionReference<"mutation", "internal">>(
    mutation: Mutation,
    args: FunctionArgs<Mutation>,
  ) => Promise<FunctionReturnType<Mutation>>;
};
Example: 
// Any Convex mutation context works
export const sendMessage = mutation({
  handler: async (ctx, args) => {
    // ctx implements RunMutationCtx
    await rateLimiter.limit(ctx, "sendMessage", { key: userId });
    // ... rest of logic
  }
});
These types are satisfied by the standard Convex QueryCtx and MutationCtx types, so you typically don’t need to reference them directly. They’re used internally to ensure type safety.

Build docs developers (and LLMs) love

Get started for freeTalk to us