Rate Limits

ATHENA uses per-customer rate limiting to ensure fair usage and system stability.

Rate Limit Tiers

Tier	Requests/min	Burst	Price
Pilot	100	150	Free
Growth	500	750	$499/mo
Enterprise	1000	1500	$2,000/mo

Burst Capacity: Temporary spikes above the rate limit are allowed up to the burst value. Sustained traffic above the limit will be throttled.

Rate Limit Headers

Every API response includes rate limit information:

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1703505600

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

Rate Limit Exceeded

When you exceed the rate limit:

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

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 60 seconds.",
    "retry_after": 60
  }
}

Handling Rate Limits

JavaScript SDK

The SDK handles rate limits automatically with exponential backoff:

import { Athena, RateLimitError } from '@athena-ai/sdk';

const athena = new Athena({ 
  apiKey: 'YOUR_API_KEY',
  maxRetries: 3  // Automatic retry with backoff
});

try {
  await athena.calibrate.analyze({ ... });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry in ${error.retryAfter}s`);
  }
}

Python SDK

from athena import Athena, RateLimitError

athena = Athena(api_key='YOUR_API_KEY', max_retries=3)

try:
    result = athena.calibrate.analyze(...)
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")

Manual Implementation

async function callWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        const retryAfter = error.retryAfter || Math.pow(2, i) * 1000;
        await new Promise(r => setTimeout(r, retryAfter * 1000));
        continue;
      }
      throw error;
    }
  }
}

Best Practices

1. Batch Requests: Combine multiple operations where possible

2. Cache Results: Cache trust scores for short periods

3. Monitor Usage: Check X-RateLimit-Remaining proactively

4. Implement Backoff: Use exponential backoff for retries

Upgrading Your Limit

Need higher limits?

Option	Action
Upgrade Tier	Dashboard → Billing → Upgrade
Enterprise Custom	Contact [email protected]

Enterprise customers can negotiate custom rate limits up to 10,000 requests/minute.

---

Next: Core Concepts