Call Count Rate Limiter

Call Count Rate Limiter

The Call Count rate limiter is the simplest and most commonly used rate limiter in ApiCharge. It restricts the total number of API calls a client can make during an ApiCharge Subscriptions by counting each request.

How It Works

The Call Count rate limiter works by:

1. Starting with a configured maximum number of calls (the Count property)
2. Tracking each request made to the API as one "permit" used
3. Rejecting requests once the total call count is reached

Unlike other rate limiters, Call Count is not time-sensitive within the subscription duration. It tracks the absolute number of calls regardless of how quickly they are made. Once the limit is reached, no more calls are allowed until a new subscription is purchased.

Feature Capabilities

The Call Count rate limiter provides these key capabilities:

• Precise metering: Tracks exact request counts regardless of request size
• Configurable limits: Set different maximums for different service tiers
• Subscription binding: Counts are tied to each subscription's duration
• Automatic enforcement: Requests beyond the limit are automatically rejected
• Header monitoring: Clients can track remaining calls through response headers

Configuration

To configure a Call Count rate limiter in your quote definition, use the following syntax:

{
  "ApiChargeQuotes": {
    "Quotes": [
      {
        "RouteId": "basic-api",
        "Duration": 3600,
        "MicroUnitPrice": 100000,
        "RateLimiters": [
          {
            "$type": "CallCount",
            "Count": 100
          }
        ]
      }
    ]
  }
}

In this example:

• "$type": "CallCount" - Specifies the rate limiter type
• "Count": 100 - Allows a maximum of 100 API calls during the subscription

Multiple Tier Example

You can create multiple service tiers with different call count limits:

{
  "ApiChargeQuotes": {
    "Quotes": [
      {
        "RouteId": "api-service",
        "Duration": 3600,
        "MicroUnitPrice": 50000,
        "RateLimiters": [
          {
            "$type": "CallCount",
            "Count": 100
          }
        ]
      },
      {
        "RouteId": "api-service",
        "Duration": 3600,
        "MicroUnitPrice": 200000,
        "RateLimiters": [
          {
            "$type": "CallCount",
            "Count": 1000
          }
        ]
      },
      {
        "RouteId": "api-service",
        "Duration": 3600,
        "MicroUnitPrice": 500000,
        "RateLimiters": [
          {
            "$type": "CallCount",
            "Count": 10000
          }
        ]
      }
    ]
  }
}

This configuration creates three tiers of service (Basic, Premium, and Enterprise) with increasing call limits at different price points.

Response When Limit Is Reached

When a client reaches the Call Count limit, ApiCharge responds with:

• HTTP Status: 429 Too Many Requests
• Response body: "Too Many Requests"

Clients should handle this status code and either wait for the next subscription period or purchase a new subscription with a higher limit.

Performance Considerations

The Call Count rate limiter is the most lightweight of all rate limiters in ApiCharge:

• Memory overhead: Very low, requiring only an integer counter per active subscription
• CPU overhead: Minimal, involving a simple increment and comparison operation
• Scaling: Scales efficiently across clustered deployments when using Redis for state persistence

Use Cases

REST API Monetization

The most common use case is for REST APIs where each API call represents a distinct operation that has a specific cost. For example:

• A weather API that limits users to 1,000 forecasts per subscription
• A geocoding API that charges based on the number of lookups
• A financial data API that limits the number of stock quote requests

Function-as-a-Service (FaaS)

For serverless function endpoints, the Call Count limiter can directly correlate to execution costs:

• An image processing function with a limit of 100 transforms
• A document conversion service with a limit of 50 conversions
• A machine learning prediction endpoint with a limit of 1,000 predictions

Mixed with Other Rate Limiters

Call Count is often combined with other rate limiters to create comprehensive QoS controls:

{
  "RouteId": "ai-inference",
  "Duration": 86400,
  "MicroUnitPrice": 1000000,
  "RateLimiters": [
    {
      "$type": "CallCount",
      "Count": 1000
    },
    {
      "$type": "DataLimitUpload",
      "Bytes": 104857600
    }
  ]
}

This configuration limits both the number of calls (1,000) and the total upload data (100 MB), providing protection against both frequent small requests and infrequent large requests.

Next Steps

Now that you understand the Call Count rate limiter, you can explore other rate limiter types:

• Data Limits - Control the amount of data transferred
• Stream Rate - Control bandwidth for streaming connections