Rate Limiting

Rate limiting protects your Prividium™ deployment by restricting how many requests a client can make within a time window. This prevents abuse, ensures fair resource allocation, and maintains service availability.

Overview

When enabled, rate limiting applies per-client limits based on either user ID (for authenticated requests) or IP address (for unauthenticated requests). Clients that exceed their limit receive an HTTP 429 response and must wait before making additional requests.

Configuration

Rate limiting is controlled via environment variables:

Variable	Default	Description
`RATE_LIMIT_ENABLED`	`true`	Enable or disable rate limiting globally
`RATE_LIMIT_AUTH_MAX`	`100`	Max requests per window for authentication endpoints
`RATE_LIMIT_PUBLIC_MAX`	`300`	Max requests per window for public endpoints
`RATE_LIMIT_USER_MAX`	`300`	Max requests per window for authenticated user routes
`RATE_LIMIT_RPC_MAX`	`1000`	Max requests per window for RPC endpoints
`RATE_LIMIT_M2M_MAX`	`1000`	Max requests per window for M2M application requests
`RATE_LIMIT_WINDOW_MS`	`60000`	Time window in milliseconds (default: 1 minute)

Rate Limit Tiers

Different endpoint categories have different limits to match their expected usage patterns:

Authentication Endpoints (`RATE_LIMIT_AUTH_MAX`)

Applies to login, token refresh, and session management routes. Lower limits help prevent credential stuffing and brute force attacks.

Public Endpoints (`RATE_LIMIT_PUBLIC_MAX`)

Applies to unauthenticated public routes. Limits are based on client IP address.

User Endpoints (`RATE_LIMIT_USER_MAX`)

Applies to authenticated API routes. Limits are tracked per user ID when authenticated, falling back to IP address for unauthenticated requests.

RPC Endpoints (`RATE_LIMIT_RPC_MAX`)

Applies to JSON-RPC proxy requests. Higher limits accommodate typical dApp interaction patterns where multiple RPC calls are made in rapid succession.

M2M Application Requests (`RATE_LIMIT_M2M_MAX`)

Applies to requests authenticated with an M2M application API key, both on the JSON-RPC proxy and on the /api/m2m-app-queries routes. Limits are tracked per API key (not per IP), so one application's keys are isolated from each other and a key cannot raise its quota by distributing calls across multiple source IPs.

Exempt Actors

Certain actors bypass rate limiting entirely to ensure critical operations are never throttled:

Tenants (legacy)

Consumers authenticated via tenant credentials are exempt from rate limits. These are typically trusted backend services with their own rate limiting. Tenants are a legacy feature, disabled by default; new integrations use M2M applications, which follow the standard RATE_LIMIT_M2M_MAX tier.

Services (legacy)

Service accounts bypass rate limits. Service authentication is a legacy mechanism superseded by M2M applications.

Users with System Permissions

Users with any of the following system permissions are exempt:

full_sequencer_rpc_access
full_read_access
contract_deployment
admin_read

This ensures administrators and elevated users can perform high-frequency operations without being throttled.

Response Headers

When rate limiting is enabled, responses include headers to help clients track their quota:

Header	Description
`x-ratelimit-limit`	Maximum requests allowed in the current window
`x-ratelimit-remaining`	Requests remaining in the current window
`x-ratelimit-reset`	Unix timestamp when the current window resets
`retry-after`	Seconds to wait before retrying (on 429 responses)

Error Response

When a client exceeds the rate limit, they receive:

HTTP Status: 429 Too Many Requests
Error Code: RATE_LIMIT_ERROR
Message: Includes the number of seconds to wait before retrying

Example response:

{
  "error": {
    "code": "RATE_LIMIT_ERROR",
    "message": "Rate limit exceeded. Try again in 45 seconds."
  }
}

Best Practices

Start with defaults: The default values are suitable for most deployments.
Monitor before adjusting: Use metrics to understand actual traffic patterns before changing limits.
Use system permissions sparingly: While system permissions bypass rate limits, they also grant elevated access. Only assign them when genuinely needed.