Rate Limiters Overview
Rate limiters are the mechanisms that enforce quality of service (QoS) parameters for ApiCharge Subscriptions in ApiCharge. They define exactly what a client is allowed to do during their access period and are a core part of the monetization model.
Rate Limiter Types
ApiCharge provides several rate limiter types that can be combined to create sophisticated service tiers:
| Type | Description | Use Case |
|---|---|---|
| Call Count | Limits the total number of API calls | REST APIs, function calls |
| Data Limit Upload | Limits the total amount of data uploaded | File uploads, data ingestion |
| Data Limit Download | Limits the total amount of data downloaded | Content delivery, data export |
| Stream Rate Upload | Controls upload bandwidth (bytes per second) | Live streaming, real-time data submission |
| Stream Rate Download | Controls download bandwidth (bytes per second) | Video streaming, audio streaming |
Rate Limiter Configuration
Rate limiters are configured as part of the quote definition in the ApiChargeQuotes section of appsettings.json:
{
"ApiChargeQuotes": {
"Quotes": [
{
"RouteId": "basic-route",
"Duration": 3600,
"MicroUnitPrice": 100000,
"RateLimiters": [
{
"$type": "CallCount",
"Count": 100
},
{
"$type": "DataLimitDownload",
"Bytes": 10485760
}
]
}
]
}
}In this example, the quote for the "basic-route" includes two rate limiters:
- A CallCount limiter that allows 100 API calls
- A DataLimitDownload limiter that allows 10 MB of data to be downloaded
The quote is valid for 1 hour (3600 seconds) and costs 0.01 XLM (100,000 micro units).
Rate Limiter Combinations
One of the most powerful features of ApiCharge is the ability to combine multiple rate limiters to create precisely defined service tiers. When multiple rate limiters are specified, they all apply simultaneously.
Example: Video Streaming Service
{
"RouteId": "video-stream",
"Duration": 7200,
"MicroUnitPrice": 500000,
"RateLimiters": [
{
"$type": "StreamRateDownload",
"BytesPerSecond": 1048576,
"WindowDurationInSeconds": 60
},
{
"$type": "DataLimitDownload",
"Bytes": 2147483648
}
]
}This configuration creates a video streaming service with:
- A maximum bandwidth of 1 MB/s (sufficient for HD video)
- A total data transfer limit of 2 GB
- A duration of 2 hours
- A price of 0.05 XLM
Service Tiers with Multiple Quotes
You can define multiple quotes for the same route to create different service tiers:
{
"ApiChargeQuotes": {
"Quotes": [
{
"RouteId": "api-service",
"Duration": 3600,
"MicroUnitPrice": 50000,
"RateLimiters": [
{
"$type": "CallCount",
"Count": 100
},
{
"$type": "DataLimitDownload",
"Bytes": 10485760
}
]
},
{
"RouteId": "api-service",
"Duration": 3600,
"MicroUnitPrice": 200000,
"RateLimiters": [
{
"$type": "CallCount",
"Count": 1000
},
{
"$type": "DataLimitDownload",
"Bytes": 104857600
}
]
},
{
"RouteId": "api-service",
"Duration": 3600,
"MicroUnitPrice": 500000,
"RateLimiters": [
{
"$type": "CallCount",
"Count": 10000
},
{
"$type": "DataLimitDownload",
"Bytes": 1073741824
}
]
}
]
}
}This configuration creates three service tiers for the same API:
- Basic Tier: 100 calls, 10 MB download, 0.005 XLM
- Premium Tier: 1,000 calls, 100 MB download, 0.02 XLM
- Enterprise Tier: 10,000 calls, 1 GB download, 0.05 XLM
Clients can choose which tier best fits their needs when purchasing an ApiCharge Subscriptions.
How Rate Limiting Functions
ApiCharge rate limiters provide controlled resource access throughout an ApiCharge Subscriptions's lifetime:
- Each rate limiter type enforces specific resource constraints (calls, data transfer, bandwidth)
- Resource usage is tracked as clients interact with your API
- When limits are reached, further access is automatically restricted
- Usage metrics are maintained throughout the subscription's duration
For persistent connections like WebSockets and Server-Sent Events, limits are enforced seamlessly in real-time, providing precise control over both total data transferred and bandwidth utilization.
Rate Limit Consistency
ApiCharge ensures consistent rate limiting experiences across all types of deployments:
- Durable Tracking: Usage metrics remain accurate even across service restarts
- Distributed Consistency: In multi-server deployments, rate limits remain synchronized
- Connection Independence: Limits are enforced consistently regardless of client connection patterns
This architecture ensures clients experience consistent service quality regardless of your deployment model, while preventing limit circumvention through connection switching or load balancer manipulation.
Error Handling
When a rate limit is exceeded, ApiCharge returns appropriate HTTP status codes:
- HTTP 429 (Too Many Requests): Returned when a call count or request rate limit is exceeded
- HTTP 413 (Payload Too Large): May be returned when a data upload limit would be exceeded
- Streaming Throttling: For streaming connections, the data flow is throttled to comply with rate limits rather than disconnecting the client
Clients can use these status codes to detect rate limiting and adjust their behavior accordingly.
Best Practices
Here are some recommendations for effective rate limiter configuration:
- Combine Multiple Types: Use different rate limiter types together to create comprehensive QoS controls
- Clear Differentiation: Ensure your service tiers have clear differences in capabilities to justify price differences
- Consider Protocol: Choose appropriate limiters for the protocol (e.g., StreamRate for WebSockets, CallCount for REST)
- Match Resource Costs: Align rate limits with the actual resource costs of serving the API
- Performance Testing: Test your rate limits under load to ensure they provide the expected QoS
Next Steps
Explore each rate limiter type in detail:
- Call Count - Control the number of API calls
- Data Limits - Control the amount of data transferred
- Stream Rate - Control bandwidth for streaming connections