Rate Limits
Understanding API rate limits and how to handle them gracefully in your applications.
Rate Limit Headers
Every API response includes headers that help you track your current rate limit status:
| Header | Description |
|---|---|
| RateLimit-Limit | Maximum requests allowed in the current window |
| RateLimit-Remaining | Remaining requests in the current window |
| RateLimit-Reset | Unix timestamp when the window resets |
| Retry-After | Seconds to wait (only included when rate limited) |
Limits by Plan
| Plan | Requests/min | Tests/month |
|---|---|---|
| Free | 20 | 25 (one-time) |
| Starter | 60 | 250 |
| Team | 120 | 1,000 |
| Business | 300 | 7,500 |
| Enterprise | Custom | Unlimited |
Handling Rate Limit Errors
When you exceed the rate limit, the API returns a 429 Too Many Requests response:
{
"error": {
"type": "rate_limit_error",
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded. Please retry after 30 seconds.",
"fix": "Implement exponential backoff or reduce request frequency.",
"doc_url": "https://docs.reachscore.co/docs/getting-started/rate-limits",
"request_id": "req_abc123xyz"
}
}Best Practices
Implement Exponential Backoff
When rate limited, wait and retry with increasing delays. Start with 1 second, then 2, 4, 8, etc.
Monitor Rate Limit Headers
Track RateLimit-Remaining and slow down before hitting the limit.
Use Webhooks for Results
Instead of polling for test results, configure webhooks to receive notifications when tests complete.
Example: Retry Logic
async function requestWithRetry(url, options, maxRetries = 3) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
const response = await fetch(url, options);
if (response.status === 429) {
const retryAfter = response.headers.get('Retry-After') ||
Math.pow(2, attempt);
console.log(`Rate limited. Retrying in ${retryAfter}s...`);
await sleep(retryAfter * 1000);
continue;
}
return response;
}
throw new Error('Max retries exceeded');
}Need Higher Limits?
If you consistently need more capacity, consider upgrading your plan or contact us for custom enterprise limits.