Rate Limiting & Throttling

The Aevum Zenth API enforces rate limits to ensure platform stability, fair resource distribution, and protection against abusive traffic. Understanding these limits is critical for building resilient integrations.

Rate Limit Tiers #

Rate limits are determined by your subscription tier, API key scope, and endpoint complexity. All limits are calculated using a sliding window algorithm.

Tier	Requests / Minute	Requests / Day	Burst Allowance	Concurrent Connections
Sandbox / Free	60	5,000	10 req/sec	2
Developer	300	50,000	25 req/sec	5
Pro	1,200	500,000	50 req/sec	15
Enterprise	Custom	Unlimited	Dedicated Gateway	Dedicated
Partner / ISV	Custom	Unlimited	Priority Routing	Priority

Response Headers #

Every API response includes rate limit metadata in standard HTTP headers. Monitor these values to implement efficient retry logic.

X-RateLimit-Limit

Maximum number of requests allowed per minute for your tier.

X-RateLimit-Remaining

Number of requests remaining in the current window.

X-RateLimit-Reset

Unix timestamp when the rate limit window resets.

Retry-After

Seconds to wait before retrying (only present on 429 responses).

Handling 429 Responses #

When you exceed your rate limit, the API returns HTTP 429 Too Many Requests. The response body includes a machine-readable error payload and actionable guidance.

                    HTTP 429 Response
                    JSON
                
// Headers
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1735689600
Retry-After: 45

// Body
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after 45 seconds.",
    "retry_after_seconds": 45,
    "documentation_url": "https://api.aevumzenth.dev/docs/rate-limiting"
  }
}

Best Practices #

Implement Exponential Backoff: Start with a short delay (e.g., 1s) and double it on each consecutive 429 response, up to a maximum of 60s. Add jitter to prevent thundering herd scenarios.
Cache Aggressively: Use conditional requests (If-None-Match) and respect Cache-Control headers to reduce redundant API calls.
Batch When Possible: Utilize batch endpoints (/v2/batch) to combine multiple operations into a single request, conserving your quota.
Monitor Headers Proactively: Don't wait for a 429. Track X-RateLimit-Remaining and throttle client-side when values drop below 10%.
Use Webhooks for State Changes: Polling heavily consumes limits. Subscribe to event webhooks for real-time updates instead.

⚠️

Important: Intentionally bypassing rate limits using multiple API keys, IP rotation, or automated bypass scripts violates the Aevum Zenth Acceptable Use Policy and will result in immediate account suspension.

Requesting Limit Increases #

If your application legitimately requires higher throughput than your current tier allows, you can request a temporary or permanent increase. Enterprise and Partner clients are routed to a dedicated infrastructure pool.

Submit a request via the Developer Console or contact your account manager.
Provide usage metrics, traffic patterns, and business justification.
Review will typically complete within 1–3 business days.
Approved increases are applied at the API key level and reflected in real-time.

Need Custom Rate Limits?

Enterprise and partner integrations receive dedicated throughput, priority routing, and SLA-backed availability.

Contact Sales Team →