API Rate Limiting & Throttling

To protect AuthVaultix infrastructure and client applications from Denial of Service (DoS) attacks, brute-force credential stuffing, and API spamming, AuthVaultix uses a high-performance Dual-Engine Rate Limiter.

High-Availability Rate Limiting Architecture

AuthVaultix handles rate limiting at the API gateway layer using in-memory atomic counters with database failover:

Primary Engine — Redis (In-Memory Atomic Counting): Requests are tracked instantly using Redis INCR and EXPIRE primitives. Redis processes requests with sub-millisecond latency.

Fallback Engine — MySQL (Relational Persistence): If Redis becomes temporarily unavailable or is under maintenance, rate limit counters automatically fall back to a SQL-backed persistence layer so the service remains uninterrupted.

Default Scopes & Rate Quotas

AuthVaultix divides API endpoints into specific Scopes with tailored rate limits so both security and high performance are maintained:

Rate Limit Scope	Target Endpoints	Default Limit	Window Duration	Description
`global`	`/api/1.0/`	30 Requests	60 Seconds	Standard quota for distributed client applications and GUI loaders.
`Seller API`	`/api/seller/*`	10 Requests	60 Seconds	Administrative REST API scope for license generation, user management, and Discord bots.
`auth_strict`	`/api/1.0/register.php`, `/api/1.0/forgot.php`	5 Requests	60 Seconds	Strict limit for registration and password reset endpoints to prevent brute-force attacks.

HTTP Response Headers Specification

AuthVaultix attaches rate limiting metadata headers to every API response, including both successful and throttled requests. Your client SDKs can read these headers and adjust request rates accordingly:

Response Header Breakdown:

X-RateLimit-Limit: The total maximum allowed requests for the given scope in the current time window.

X-RateLimit-Remaining: The number of remaining allowed requests in the current window before throttling occurs.

X-RateLimit-Reset: A Unix timestamp indicating when the current rate limit window resets.

Retry-After: Included only in throttled (HTTP 429) responses. It tells the client how many seconds to wait before retrying.

Throttled Response (HTTP 429)

When a client application exceeds the allowed rate limit for a scope, the server stops processing the request immediately, returns the HTTP status code 429 Too Many Requests, and sends a JSON error response:

HTTP Response Status & Headers:

JSON Response Body:

{
  "success": false,
  "message": "Rate limit exceeded. Try again in 45s.",
  "retry_after": 45
}

Developer Best Practices & SDK Handling

To reduce rate limit impact for genuine end users, follow these guidelines when building client apps and custom web panels:

1. Implement Exponential Backoff with Jitter

Do not retry failed requests immediately in tight loops (while(true)). When you receive an HTTP 429 status code or a retry_after field, wait for the provided duration plus a small random delay (jitter) before sending the next request.

2. Avoid High-Frequency Heartbeat Polling

Do not call session validation (client.check()) every second. Schedule heartbeat checks in a background worker thread at reasonable intervals, such as every 5 to 10 seconds.

3. Use Batch Variable Retrieval

Instead of sending separate HTTP requests for individual variables, fetch all required variables in a single request at startup and cache them in local application memory.

Next Steps & Deep-Dive Links

Explore other AuthVaultix architectural guides here:

Security Practices & Cryptographic Architecture

Frequently Asked Questions & Technical Q&A

SDK & Code Examples Hub

rate limiting

API Rate Limiting & Throttling#

High-Availability Rate Limiting Architecture#

Default Scopes & Rate Quotas#

HTTP Response Headers Specification#

Response Header Breakdown:#

Throttled Response (HTTP 429)#

HTTP Response Status & Headers:#

JSON Response Body:#

Developer Best Practices & SDK Handling#

1. Implement Exponential Backoff with Jitter#

2. Avoid High-Frequency Heartbeat Polling#

3. Use Batch Variable Retrieval#

Next Steps & Deep-Dive Links#