Expand AI logo
DocsAPI ReferenceAPI Reference
Login

API Reference

Getting Started

API ReferenceRate LimitingError Handling

Endpoints

BatchedFetchFetch JsonFetch SearchGet Batched

Rate Limiting

Understanding API rate limits and how to handle them

The Expand API implements rate limiting to ensure fair usage and maintain service quality for all users.

How Rate Limiting Works

Rate limits are applied per organization. When you exceed your rate limit, the API returns a 429 Too Many Requests status.

Rate Limit Response

When rate limited, the API returns:

  • Status Code: 429
  • Error Tag: TooManyRequests
{
  "_tag": "TooManyRequests"
}

Handling Rate Limits

With SDKs

Both SDKs provide a RateLimitError that you can catch and handle:

import Expand, { RateLimitError } from 'expandai'

const client = new Expand({ apiKey: '{{API_KEY}}' })

try {
  const result = await client.fetch({ url: 'https://example.com' })
} catch (error) {
  if (error instanceof RateLimitError) {
    // Wait and retry
    console.log('Rate limited, retry after:', error.retryAfter)

Retry Strategy

We recommend implementing exponential backoff when you encounter rate limits:

  1. Wait 1 second, then retry
  2. If still rate limited, wait 2 seconds
  3. Continue doubling the wait time up to a maximum (e.g., 32 seconds)
  4. After maximum retries, surface the error to the user
async function fetchWithRetry(url: string, maxRetries = 5) {
  let delay = 1000

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await client.fetch({ url })
    } catch (error) {
      if (error instanceof RateLimitError && attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, delay))
        delay *= 2
      }

Best Practices

  • Batch requests when possible to reduce the number of API calls
  • Cache responses to avoid redundant fetches for the same URL
  • Monitor usage via the dashboard to understand your patterns
  • Implement retries with exponential backoff to handle transient rate limits gracefully

Need Higher Limits?

If you need higher rate limits for your use case, contact us at support@expand.ai to discuss enterprise options.

On This Page

How Rate Limiting WorksRate Limit ResponseHandling Rate LimitsWith SDKsRetry StrategyBest PracticesNeed Higher Limits?
}
}
from expandai import Expand, RateLimitError

client = Expand(api_key="{{API_KEY}}")

try:
    result = client.fetch(url="https://example.com")
except RateLimitError as e:
    # Wait and retry
    print(f"Rate limited, retry after: {e.retry_after}")
else
{
throw error
}
}
}
}