Rate Limits

Entity Detector uses daily request quotas based on your subscription plan. Understanding these limits helps you build reliable applications.

Plan Quotas

How Quotas Work

• Daily reset - Quotas reset at midnight UTC
• Per-account - All API tokens under your account share the same quota
• Cached requests - Requests served from cache still count toward your quota
• Failed requests - Requests that result in errors (4xx, 5xx) do not count

Checking Your Quota

Use the /v1/quota endpoint to check your current usage:

curl https://api.entitydetector.com/v1/quota \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "plan": "starter",
  "daily": {
    "limit": 1000,
    "used": 342,
    "remaining": 658
  },
  "resetAt": "2024-01-16T00:00:00Z"
}

Rate Limit Headers

Every API response includes headers with your current quota status:

Handling Rate Limits

When you exceed your quota, you'll receive a 429 Too Many Requests response:

{
  "error": "Rate Limited",
  "message": "Daily quota exceeded. Resets at 2024-01-16T00:00:00Z",
  "code": "QUOTA_EXCEEDED",
  "retryAfter": 3600
}

Best Practices

1. Monitor your usage - Check the rate limit headers on each response
2. Implement retry logic - Use exponential backoff when rate limited
3. Cache results - Store API responses to avoid duplicate requests
4. Queue requests - Spread requests throughout the day if possible

Retry with Backoff Example

async function analyzeWithRetry(text, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch('https://api.entitydetector.com/v1/analyze', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.API_KEY}`
      },
      body: JSON.stringify({ text })
    });

    if (response.status === 429) {
      const data = await response.json();
      const retryAfter = data.retryAfter || 60;
      console.log(`Rate limited. Retrying in ${retryAfter}s...`);
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }

    return response.json();
  }
  throw new Error('Max retries exceeded');
}

Caching

Entity Detector automatically caches analysis results for identical text for 24 hours. When a result is served from cache:

• Response includes "cached": true in the meta object
• Processing time is near-instant
• The request still counts toward your quota

Upgrading Your Plan

If you consistently hit your quota limits, consider upgrading your plan:

• Upgrade instantly from your dashboard
• Changes take effect immediately
• Prorated billing for mid-cycle upgrades

Need Higher Limits?

For enterprise needs exceeding 50,000 daily requests, contact us for custom pricing and dedicated infrastructure options.