Feature: Rate Limiting
Relevant source files
The following files were used as context for generating this wiki page:Rate limiting is a production-ready feature within MessageJS designed to control the traffic sent to the API. Its primary purpose is to ensure system stability, prevent abuse, and guarantee fair usage across all users. The system enforces limits on both message sending via the SDK and management operations via the Dashboard API.
These limits are primarily configured on a per-API-key basis, allowing for granular control over request frequency. When a limit is surpassed, the API responds with a specific error code, enabling client applications to handle the situation gracefully, for instance, by implementing backoff and retry logic.
Sources: README.md:20, API_REFERENCE.md:328-338
Configuration and Management
Rate limits are set when an API key is created within a project. The MessageJS dashboard provides an interface to optionally specify a rate limit during key generation. This is also exposed through the Dashboard API.
Sources: QUICK_START.md:50-53, API_REFERENCE.md:141-147
API Key Creation
When creating an API key via the POST /api/v1/projects/:projectId/keys endpoint, a rateLimit can be specified in the request body.
| Parameter | Type | Description |
|---|---|---|
name | string | A descriptive name for the API key. |
rateLimit | number | The number of requests allowed per unit of time (e.g., per hour). |
Sources: API_REFERENCE.md:144-147
Data Model Integration
The rate limit configuration is stored as part of the APIKey data model. The APIKey interface includes a rateLimitConfig property, which holds the project-specific rate limit settings for that key. Each APIKey is associated with a Project.
The diagram below illustrates the relationship between a User, their Projects, and the API Keys with rate limit configurations.
This diagram shows that a User can own multiple Projects, and each Project can contain multiple APIKeys, each with its own rateLimitConfig.
Sources: packages/core/src/types/dataModels.ts:34-42, packages/core/prisma/schema.prisma:57-66
Types of Rate Limits
MessageJS defines distinct rate limits for different parts of the system: API key usage for sending messages and Dashboard API usage for management tasks.
Sources: API_REFERENCE.md:328-338
API Key Limits
These limits apply to requests made using an API key, primarily for sending messages via the SDK. The limits vary based on the user's subscription tier.
| Tier | Limit |
|---|---|
| Free Tier | 1,000 messages/hour |
| Pro Tier | 10,000 messages/hour |
| Enterprise | Custom limits |
Sources: API_REFERENCE.md:330-334
Dashboard API Limits
These limits apply to authenticated requests made to the Dashboard API endpoints (e.g., creating projects, managing connectors). The limits are applied on a per-user basis.
| Tier | Limit |
|---|---|
| Standard | 100 requests/minute |
| Pro | 500 requests/minute |
Sources: API_REFERENCE.md:336-338
Enforcement and Error Handling
Rate limit enforcement is a critical part of the API's request lifecycle. This check would logically occur within the authentication middleware after an API key has been validated but before the request is passed to the controller.
Sources: packages/core/src/api/middleware/authMiddleware.ts
The following sequence diagram shows the flow of a client request that exceeds the defined rate limit.
This diagram illustrates the API's response when a rate limit is breached, preventing the request from reaching the application logic.
Error Responses
When a client exceeds a configured rate limit, the API returns an HTTP 429 Too Many Requests status code. The response body contains a structured error object.
| Code | HTTP Status | Description |
|---|---|---|
RATE_LIMIT_EXCEEDED | 429 | Rate limit exceeded. |
QUOTA_EXCEEDED | 429 | Monthly quota exceeded. |
Clients should be designed to handle this 429 response, typically by implementing an exponential backoff strategy before retrying the request.
Sources: API_REFERENCE.md:312-315
Summary
The rate limiting feature in MessageJS is a fundamental component for maintaining a healthy and reliable API service. It is enforced at two levels: for message sending via API keys and for management operations via the Dashboard API. Configuration is managed at the individual API key level, providing developers with the flexibility to control request rates based on their application's needs. When limits are exceeded, the system provides clear error codes, allowing for robust error handling and retry mechanisms on the client side.