Rate Limits

HX-Gate enforces per-tenant rate limits using a sliding-window algorithm. Each tenant's limit is determined by their billing tier.

---

Default limits

Tier	Requests	Window	Effective rate
Starter	10	60 s	~0.17 req/s
Builder	100	60 s	~1.7 req/s
Pro	1,000	60 s	~16.7 req/s
Enterprise	Custom	Custom	Custom

---

How it works

1. Each request from a tenant increments a counter keyed by tenant_id.
2. The counter uses a sliding window of window_s seconds.
3. If the count exceeds the limit, the request is rejected before forwarding to the engine.

The counter is tracked in-memory (single instance) or in Redis (multi-instance deployments).

---

Rate limit headers

Every response includes rate limit information:

Header	Description
X-RateLimit-Limit	Maximum requests per window
X-RateLimit-Remaining	Remaining requests in current window
X-RateLimit-Reset	Unix timestamp when the window resets

---

Exceeded responses

When rate limited, the gate returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{
  "detail": "Rate limit exceeded for tenant 'acme-corp'. Retry after 12s."
}

Client handling

Pythoncurl

import time
from holonomix import HolonomiX, HolonomiXError

hx = HolonomiX(url="https://gate.holonomx.com", api_key="hx_live_...")

def put_with_retry(key, data, max_retries=3):
    for attempt in range(max_retries):
        try:
            return hx.put(key, data)
        except HolonomiXError as e:
            if e.status_code == 429 and attempt < max_retries - 1:
                time.sleep(2 ** attempt)
            else:
                raise

# Check remaining quota before bulk operations
curl -v https://gate.holonomx.com/v1/list/default \
  -H "X-Api-Key: $HX_API_KEY" 2>&1 | grep -i ratelimit

---

Configuration (self-hosted)

Override default limits in the Gate environment:

Variable	Type	Default	Description
HX_GATE_DEFAULT_RATE_LIMIT_REQUESTS	int	100	Default requests per window
HX_GATE_DEFAULT_RATE_LIMIT_WINDOW_S	int	60	Window duration in seconds

Per-tenant overrides are set via the onboarding API:

curl -X POST https://gate.holonomx.com/gate/onboard/update-tier \
  -H "Authorization: Bearer $SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "acme-corp", "plan": "pro"}'

---

Best practices

• Batch operations: Use put_cores_batch for bulk ingestion to reduce request count.
• Cache metadata: GET responses are stable per version — cache aggressively.
• Exponential backoff: Always implement retry with backoff for 429 responses.
• Monitor headers: Track X-RateLimit-Remaining to pre-empt throttling.
• Upgrade tier: If you consistently hit limits, upgrade via the Console or contact sales for Enterprise.