Rate Limiters

RateLimiterConfig — top-level fields

RateLimitStoreConfig

redis sub-fields:

RateLimitBudgetConfig

RateLimitRuleConfig

Period enum — valid values for period:

second | minute | hour | day | week | month | year

Short forms like 1s, 1m are accepted as aliases for second / minute.

rateLimitAutoTune — per-upstream dynamic adjustment

The auto-tuner is enabled by default when an upstream has a rateLimitBudget set. It monitors the 429 error rate from that upstream and adjusts maxCount up or down.

upstreams:
  - id: my-upstream
    endpoint: https://rpc.example.com
    rateLimitBudget: example-budget
    rateLimitAutoTune:
      enabled: true                  # default: true
      adjustmentPeriod: 1m           # how often to re-evaluate; default: 1m
      errorRateThreshold: 0.1        # 429 error rate above this triggers decrease; default: 0.1
      increaseFactor: 1.05           # multiply maxCount by this when under threshold; default: 1.05
      decreaseFactor: 0.9            # multiply maxCount by this when over threshold; default: 0.9
      minBudget: 1                   # floor; set >= 1 so traffic never stops; default: 0
      maxBudget: 10000               # ceiling; default: 10000

Metric: erpc_rate_limiter_budget_max_count{budget,method} — watch this to verify the auto-tuner is moving.

Where budgets can be applied

Budgets are composed across four layers. eRPC evaluates each independently; the first over-limit layer stops the request.

Rule matching and evaluation

• method supports wildcards (*). Rules are checked in order; all matching rules are evaluated (not just the first). Any over-limit result rejects the request.
• Put narrower rules (e.g. eth_trace*) before broader ones (*) within a budget so they take effect independently.
• Scope descriptors (perIP, perUser, perNetwork) partition counters within a rule but do not change maxCount. Combining scopes multiplies cardinality.
• If a scoped value is missing at evaluation time (e.g. perUser: true but the request is unauthenticated), the rule errors for that request.

Errors returned per layer

Each error includes the budget ID and the matched rule (e.g. method:eth_getLogs) for debugging.

Full example — per-user free-trial budget

rateLimiters:
  store:
    driver: redis
    redis:
      uri: redis://localhost:6379
      getTimeout: 5s
    cacheKeyPrefix: erpc_rl_
    nearLimitRatio: 0.8
  budgets:
    - id: free-trial
      rules:
        - method: '*'
          maxCount: 10
          period: second
          perUser: true        # 10 rps per authenticated user
        - method: '*'
          maxCount: 20000
          period: day
          perUser: true
          perNetwork: true     # plus a daily cap per user per chain

Redis store with TLS

rateLimiters:
  store:
    driver: redis
    redis:
      uri: rediss://redis.internal:6380
      username: erpc
      tls:
        enabled: true
        caFile: /etc/ssl/redis-ca.crt
        certFile: /etc/ssl/redis-client.crt
        keyFile: /etc/ssl/redis-client.key
      getTimeout: 3s

Metrics reference

Common pitfalls

• store not set — eRPC fails to start. rateLimiters.store is required even when using memory.
• minBudget: 0 with auto-tuner enabled — the tuner can drive maxCount to zero; set minBudget: 1 or higher.
• perUser: true without auth — unauthenticated requests error at the rule. Only use perUser on budgets assigned to auth-gated projects or strategies.
• perIP: true behind a load balancer without trustedProxies — all requests appear as the LB IP; rate limits collapse to one counter. Set server.trustedIPForwarders and server.trustedIPHeaders.
• memory store in a multi-replica deployment — each replica counts independently. You get N times the effective limit. Use redis for shared counting across replicas.
• Budget referenced but not defined — the request is unmetered. Add the budget under rateLimiters.budgets[].
• Rule order matters — all matching rules are checked, not just the first. Put narrow rules (eth_trace*) before broad ones (*) if you want separate caps per method group.
• getTimeout: 0 on Redis — disables the fail-open timeout; a slow or unreachable Redis blocks all requests until it responds.