Rate Limits

Rate Limit Tiers

Aira enforces per-key rate limits to ensure fair usage and platform stability. The default tiers are:

Limits are evaluated on a sliding window per API key (or per IP for unauthenticated requests).

Response Headers

Every API response includes rate-limit headers so you can track your usage in real time:

Example response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1712345678

Handling 429 Responses

When you exceed your rate limit, the API returns a 429 Too Many Requests response with an error body:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Try again in 12 seconds.",
    "details": {
      "retry_after": 12
    }
  },
  "request_id": "req_rl_abc123"
}

The response also includes a Retry-After header with the number of seconds to wait:

Retry-After: 12

Recommended Retry Strategy

1. Read the Retry-After header (or error.details.retry_after from the JSON body).
2. Wait for the specified duration.
3. Retry the request.
4. If you continue to receive 429 responses, apply exponential backoff (e.g., double the wait time on each subsequent retry, up to a maximum of 60 seconds).

Both the Python and TypeScript SDKs handle retry logic automatically by default.

Plan-Based Limits

Higher rate limits are available on paid plans. Your effective limits depend on your subscription tier:

To check your current plan and limits, visit the Billing page in the Aira dashboard or call the Billing API.

If you need limits beyond what your current plan provides, contact us to discuss Enterprise options.