Rate Limiting
Understand the ErzyCall API rate limits and how to handle 429 responses.
The ErzyCall REST API enforces rate limits per API key using a sliding window algorithm.
Limits
| Window | Limit |
|---|---|
| Per minute | 60 requests |
| Per hour | 1,000 requests |
Both windows are evaluated independently. If either limit is exceeded, the request is rejected with a 429 status.
Rate Limit Headers
Every response includes rate limit headers so you can track your usage:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed in the current window |
X-RateLimit-Remaining | Requests remaining in the current window |
X-RateLimit-Reset | Unix timestamp (seconds) when the window resets |
When rate limited, an additional header is included:
| Header | Description |
|---|---|
Retry-After | Seconds to wait before retrying |
429 Response
{
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Retry after 12s"
}
}Handling Rate Limits
Exponential Backoff
The simplest approach is to respect the Retry-After header:
async function apiCall(url, options) {
const response = await fetch(url, options);
if (response.status === 429) {
const retryAfter = parseInt(response.headers.get("Retry-After") || "5");
await new Promise((r) => setTimeout(r, retryAfter * 1000));
return apiCall(url, options); // Retry
}
return response;
}Proactive Throttling
Monitor the X-RateLimit-Remaining header and slow down as you approach the limit:
async function apiCall(url, options) {
const response = await fetch(url, options);
const remaining = parseInt(response.headers.get("X-RateLimit-Remaining") || "60");
if (remaining < 5) {
// Approaching limit — add a delay before next request
await new Promise((r) => setTimeout(r, 2000));
}
return response;
}Tips
- Batch operations when possible instead of making many individual requests.
- Cache responses for data that doesn't change frequently (e.g., phone numbers, assistants).
- Use webhooks instead of polling for real-time updates.
- Distribute load across multiple API keys if you need higher throughput.