Limiter Config

Token bucket limiter

type TokenBucketLimiterConfig = {
  type: "token-bucket";
 
  // The max number of tokens in the bucket
  maxTokens: number;
 
  // The rate at which the bucket is refilled. The bucket is refilled `tokens` tokens every `seconds` seconds
  refillRate: {
    tokens: number;
    seconds: number;
  };
 
  // Optional
  throughput?: ThroughputConfig;
};

Fixed window limiter

type FixedWindowLimiterConfig = {
  type: "fixed-window";
 
  // The max value the limiter will allow before blocking requests
  maxValue: number;
 
  window:
    | {
        seconds: number;
 
        // Optional
        // The window will always start at a timestamp equal to the reference timestamp plus some multiple of window seconds.
        // Eg. if the reference timestamp is for Monday, 00:00:00 UTC and the window seconds is 604_800 (7 days), the window will start every week on Monday, 00:00:00 UTC.
        referenceTimestamp?: number;
      }
    | {
        months: number;
 
        // Optional
        // The window will start on the same day, hour, minute and second as the referenceTimestamp.
        // Eg. if the referenceTimestamp is for 2024 July 1st, 00:00:00 UTC, the window will start on 1st, 00:00:00 UTC of every month.
        referenceTimestamp?: number;
      };
 
  // Optional
  throughput?: ThroughputConfig;
};

Throughput provisioning

Increasing the provisioned throughput will decrease the consistency of the limiter. Limiters with a provisioned throughput of:

1000 or less requests per second are strongly consistent.
More than 1000 requests per second are eventually consistent. Increasing the limiter from 1000 to 5 million will reduce the accuracy of the limiter.

The minimum and default throughput is 1000 requests per second.

Increasing the throughput does not affect the cost per request.

If the throughput exceeds the provisioned capacity the requests will return ‘status’ as ‘blocked’ and ‘data’ field ‘throughputExceeded’ will be true.

type ThroughputConfig = {
  requestsPerSecond: number;
};

Introduction Limit API