# How to Configure Rate Limiting with Short, Medium, and Long TTL Limits in OpenWA > Learn how to configure short, medium, and long TTL rate limiting in OpenWA. Easily set environment variables to customize your API's request limits and enhance performance. - Repository: [Yudhi Armyndharis/OpenWA](https://github.com/rmyndharis/OpenWA) - Tags: how-to-guide - Published: 2026-05-21 --- **Configure short-, medium-, and long-TTL rate limiting in OpenWA by setting the `RATE_LIMIT_SHORT_TTL`, `RATE_LIMIT_MEDIUM_TTL`, and `RATE_LIMIT_LONG_TTL` environment variables, which override the defaults defined in [`src/config/configuration.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/config/configuration.ts) and are consumed by the NestJS Throttler module in [`src/app.module.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/app.module.ts).** OpenWA implements a three-tier rate limiting strategy using NestJS Throttler to protect the WhatsApp API from abuse. This architecture allows you to define distinct time-to-live (TTL) windows and request limits for short-term bursts, medium-term sustained traffic, and long-term aggregate usage, all configurable via environment variables without modifying source code. ## Understanding the Three-Tier Rate Limiting Architecture OpenWA’s rate limiting system relies on three interconnected components: the central configuration file, security middleware constants, and the Throttler module registration. ### Configuration Defaults in [`configuration.ts`](https://github.com/rmyndharis/OpenWA/blob/main/configuration.ts) The primary source of truth for rate limiting values resides in [`src/config/configuration.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/config/configuration.ts). Lines 66–76 define the `api.rateLimit` object, mapping environment variables to default values for all three tiers. | Tier | Environment Variable (TTL) | Environment Variable (Limit) | Default TTL | Default Limit | |------|---------------------------|------------------------------|-------------|---------------| | Short | `RATE_LIMIT_SHORT_TTL` | `RATE_LIMIT_SHORT_LIMIT` | 1000 ms | 10 requests | | Medium | `RATE_LIMIT_MEDIUM_TTL` | `RATE_LIMIT_MEDIUM_LIMIT` | 60000 ms | 100 requests | | Long | `RATE_LIMIT_LONG_TTL` | `RATE_LIMIT_LONG_LIMIT` | 3600000 ms | 1000 requests | Source: [[`src/config/configuration.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/config/configuration.ts)](https://github.com/rmyndharis/OpenWA/blob/main/src/config/configuration.ts#L66-L76) ### Security Constants Fallback [`src/common/security/security.middleware.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/common/security/security.middleware.ts) contains a fallback `SecurityConfig.rateLimit` object (lines 81–86) that mirrors the same default values. This ensures that if the configuration service fails to load, the application still maintains protective rate limiting boundaries. Source: [[`src/common/security/security.middleware.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/common/security/security.middleware.ts)](https://github.com/rmyndharis/OpenWA/blob/main/src/common/security/security.middleware.ts#L81-L86) ### Module Registration in [`app.module.ts`](https://github.com/rmyndharis/OpenWA/blob/main/app.module.ts) The values are injected into the application through `ThrottlerModule.forRootAsync` in [`src/app.module.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/app.module.ts) (lines 120–131). The factory function retrieves the TTL and limit values for each tier using `ConfigService.get()` and registers three separate throttler instances. Source: [[`src/app.module.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/app.module.ts)](https://github.com/rmyndharis/OpenWA/blob/main/src/app.module.ts#L120-L131) ## How to Configure Rate Limiting via Environment Variables All rate limiting parameters are configurable at runtime through environment variables. Create or modify your `.env` file in the project root to override the defaults. ```dotenv # Short-term burst protection (10 requests per second) RATE_LIMIT_SHORT_TTL=1000 RATE_LIMIT_SHORT_LIMIT=10 # Medium-term protection (100 requests per minute) RATE_LIMIT_MEDIUM_TTL=60000 RATE_LIMIT_MEDIUM_LIMIT=100 # Long-term protection (1000 requests per hour) RATE_LIMIT_LONG_TTL=3600000 RATE_LIMIT_LONG_LIMIT=1000 ``` After updating the environment variables, restart the OpenWA container or the Node.js process for the changes to take effect. The configuration is read once at startup and propagated through NestJS’s dependency injection system. ## Implementation Details and Code Examples ### How the Values Flow Through the Application 1. **Startup**: `ConfigModule` loads [`configuration.ts`](https://github.com/rmyndharis/OpenWA/blob/main/configuration.ts) and parses environment variables into the `api.rateLimit` namespace. 2. **Registration**: `ThrottlerModule.forRootAsync` extracts the six values (three TTLs and three limits) using `configService.get()`. 3. **Enforcement**: The throttler middleware applies the most restrictive limit that applies to the current request window. 4. **Headers**: As implemented in [`src/main.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/main.ts), responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. ### Example: Aggressive Short-Term Limits To restrict short-term bursts to 5 requests per 2 seconds while keeping other tiers standard: ```dotenv # .env RATE_LIMIT_SHORT_TTL=2000 RATE_LIMIT_SHORT_LIMIT=5 RATE_LIMIT_MEDIUM_TTL=60000 RATE_LIMIT_MEDIUM_LIMIT=100 RATE_LIMIT_LONG_TTL=3600000 RATE_LIMIT_LONG_LIMIT=1000 ``` Verify the headers with a test request: ```bash curl -i http://localhost:2785/api/v1/health ``` Expected response headers: ```http X-RateLimit-Limit: 5 X-RateLimit-Remaining: 4 X-RateLimit-Reset: 2 ``` ### Example: Per-Route Override with `@Throttle` For specific controllers requiring different limits, use the `@Throttle` decorator from `@nestjs/throttler` to override the global configuration: ```typescript import { Controller, Get } from '@nestjs/common'; import { Throttle } from '@nestjs/throttler'; @Controller('webhook') export class WebhookController { // Allow only 2 requests per minute for this endpoint @Get('validate') @Throttle(60, 2) // ttl: 60 seconds, limit: 2 requests validateWebhook() { return { status: 'valid' }; } } ``` ### Example: Runtime Configuration Debugging To verify the active rate limiting configuration programmatically: ```typescript import { ConfigService } from '@nestjs/config'; import { Injectable, Logger } from '@nestjs/common'; @Injectable() export class RateLimitDebugService { constructor(private readonly configService: ConfigService) {} logLimits() { const shortTtl = this.configService.get('api.rateLimit.shortTtl'); const shortLimit = this.configService.get('api.rateLimit.shortLimit'); const mediumTtl = this.configService.get('api.rateLimit.mediumTtl'); const mediumLimit = this.configService.get('api.rateLimit.mediumLimit'); const longTtl = this.configService.get('api.rateLimit.longTtl'); const longLimit = this.configService.get('api.rateLimit.longLimit'); Logger.log(`Rate Limits - Short: ${shortLimit}req/${shortTtl}ms`); Logger.log(`Rate Limits - Medium: ${mediumLimit}req/${mediumTtl}ms`); Logger.log(`Rate Limits - Long: ${longLimit}req/${longTtl}ms`); } } ``` ## Summary - OpenWA implements three-tier rate limiting (short, medium, long) via **NestJS Throttler**, configured through the `ConfigService`. - Default values are defined in **[`src/config/configuration.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/config/configuration.ts)** (lines 66–76) and mirrored in **[`src/common/security/security.middleware.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/common/security/security.middleware.ts)** (lines 81–86). - Override defaults by setting **`RATE_LIMIT_SHORT_TTL`**, **`RATE_LIMIT_MEDIUM_TTL`**, and **`RATE_LIMIT_LONG_TTL`** environment variables with their corresponding `*_LIMIT` values. - The throttler is registered in **[`src/app.module.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/app.module.ts)** (lines 120–131) using `ThrottlerModule.forRootAsync`. - Use the **`@Throttle`** decorator to override global limits for specific routes. - Changes require an application restart to take effect. ## Frequently Asked Questions ### What are the default rate limiting values in OpenWA? By default, OpenWA enforces three tiers: **short** (10 requests per 1000ms), **medium** (100 requests per 60000ms), and **long** (1000 requests per 3600000ms). These defaults are hardcoded in [`src/config/configuration.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/config/configuration.ts) and serve as fallbacks if environment variables are not set. ### How do I apply different rate limits to specific API endpoints? Apply the **`@Throttle(ttl, limit)`** decorator to individual controller methods. This overrides the global configuration for that specific route. For example, `@Throttle(60, 2)` restricts the endpoint to 2 requests per minute regardless of the global short, medium, or long settings. ### Where can I see the current rate limit status for my requests? OpenWA includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers in HTTP responses. These headers indicate the current tier’s maximum requests, remaining quota, and seconds until the limit resets, respectively. ### Do I need to restart OpenWA after changing rate limit environment variables? Yes. OpenWA reads the configuration once at startup. After modifying `.env` or your container’s environment variables, you must restart the application process or container for the new TTL and limit values to take effect.