Menu

Navigation

Getting Started

Configuration

Routes

Rate Limiters

Early Access

Credits Rate Limiter

Server-controlled dynamic credit system for sophisticated usage patterns and business models

Credit Rate Limiter

The Credit rate limiter provides a uniquely flexible consumption model where the backend service itself controls credit deduction and allocation through response headers. Unlike other rate limiters that operate purely at the proxy level, the Credit system enables sophisticated business logic to be implemented in your backend service.

Best For: Complex pricing models, promotional campaigns, usage rewards, tiered service levels, freemium models, and any scenario where credit consumption needs to be determined by sophisticated backend business logic rather than simple per-call deductions.

How Credit Rate Limiting Works

The Credit rate limiter operates through a unique server-controlled model:

  1. an ApiCharge Subscriptions is granted a specific number of total credits
  2. Each API call initially consumes 1 credit by default (unless your backend service specifies otherwise)
  3. Your backend service returns an apicharge_credits header indicating how many credits to actually deduct or add
  4. ApiCharge adjusts the credit balance based on your service's response header
  5. This enables dynamic credit control based on your business logic

This approach provides unprecedented flexibility in monetization strategies, allowing your backend service to implement complex pricing algorithms, promotional logic, and reward systems.

Configuration

To use the Credit rate limiter, add it to your route quote in appsettings.json: 

{
  "ApiChargeProxy": {
    "Routes": {
      "premium-api": {
        "ClusterId": "myCluster",
        "Match": {
          "Path": "/api/{**catch-all}"
        },
        "Quote": {
          "ServerFundsRecipient": "YOUR_STELLAR_ADDRESS",
          "PricingStrategy": {
            "$type": "Basic",
            "Duration": 3600,
            "MicroUnitPrice": 1000000
          },
          "RateLimiterStrategies": [
            {
              "$type": "Credit",
              "Credits": 100
            }
          ]
        }
      }
    }
  }
}

Configuration Properties

Property Type Description
Credits Integer The total number of credits assigned to the subscription

Server-Controlled Credit Adjustment

The key feature of the Credit rate limiter is that your backend service controls credit consumption through the apicharge_credits response header: 

HTTP/1.1 200 OK
Content-Type: application/json
apicharge_credits: -5

{
  "result": "Premium processing completed"
}

Credit Adjustment Values

Advanced Use Cases

Progressive Pricing Models

Implement sophisticated pricing where costs change based on usage patterns:

Reward-Based Systems

Reward users with credits for specific behaviors:

Feature-Based Pricing

Charge different amounts based on features used:

Promotional Campaigns

Implement time-based promotions and special offers:

Business Model Examples

Freemium API Service

Gaming API with Achievements

Educational Platform

Combined with Other Rate Limiters

Credits work excellently with other rate limiters for comprehensive service tiers: 

{
  "RateLimiterStrategies": [
    {
      "$type": "Credit",
      "Credits": 1000
    },
    {
      "$type": "CallCount",
      "Count": 500
    },
    {
      "$type": "StreamRateDownload",
      "BytesPerSecond": 1048576,
      "WindowDurationInSeconds": 3600
    }
  ]
}

Implementation Best Practices

Backend Service Guidelines

Credit Strategy Design

Error Handling

When credits are exhausted, ApiCharge returns a 429 status: 

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json

{
  "type": "https://apicharge.error/EX017",
  "title": "Insufficient Credits",
  "status": 429,
  "detail": "Your subscription has insufficient credits for this operation.",
  "instance": "/apicharge/errors/12345"
}

Monitoring and Analytics

Track credit usage patterns to optimize your pricing strategy:

Next Steps

Explore how Credits can be combined with other rate limiter types: