API Reference
Rate Limits
Understand API rate limits and how to handle them in your application.
Rate limits protect the API from abuse and ensure fair usage for all customers. When you exceed the rate limit, the API returns a 429 Too Many Requests response.
Hourly Limit
1,000
requests per hour per API key
Burst Limit
100
requests per minute per API key
Rate Limit Headers
Every API response includes headers to help you track your rate limit status:
| 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 when the window resets |
Example Response Headers
HTTP/1.1 200 OKContent-Type: application/jsonX-RateLimit-Limit: 1000X-RateLimit-Remaining: 987X-RateLimit-Reset: 1706198400Handling Rate Limits
Monitor Rate Limit Headers
Check X-RateLimit-Remaining before making requests to avoid hitting limits.
Implement Exponential Backoff
When rate limited, wait progressively longer between retries (1s, 2s, 4s, 8s, etc.).
Use the Reset Header
When limited, use X-RateLimit-Reset to know exactly when to retry.
Cache Responses
Cache API responses when possible to reduce the number of requests you need to make.
Implementation Example
class RateLimitedClient { constructor(apiKey) { this.apiKey = apiKey; this.remaining = Infinity; this.resetTime = 0; } async request(endpoint, options = {}) { // Check if we're approaching the limit if (this.remaining < 10) { const waitTime = Math.max(0, this.resetTime - Date.now()); if (waitTime > 0) { console.log(`Rate limit low, waiting ${waitTime}ms`); await this.sleep(waitTime); } } const response = await fetch(`https://dev.flametalk.ai/v1${endpoint}`, { ...options, headers: { 'Authorization': `Bearer ${this.apiKey}`, 'Content-Type': 'application/json', ...options.headers, }, }); // Update rate limit info from headers this.remaining = parseInt( response.headers.get('X-RateLimit-Remaining') || '1000' ); this.resetTime = parseInt( response.headers.get('X-RateLimit-Reset') || '0' ) * 1000; // Handle rate limit error if (response.status === 429) { const retryAfter = this.resetTime - Date.now() + 1000; console.log(`Rate limited. Retrying in ${retryAfter}ms`); await this.sleep(retryAfter); return this.request(endpoint, options); } return response.json(); } sleep(ms) { return new Promise(resolve => setTimeout(resolve, ms)); }} // Usageconst client = new RateLimitedClient(process.env.FLAMETALK_API_KEY); const agents = await client.request('/agents');console.log(agents);Rate Limit Error Response
When you exceed the rate limit, the API returns:
{ "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please slow down." }}HTTP/1.1 429 Too Many RequestsContent-Type: application/jsonX-RateLimit-Limit: 1000X-RateLimit-Remaining: 0X-RateLimit-Reset: 1706198400Retry-After: 3600Best Practices
Batch Operations When Possible
Instead of making many small requests, batch operations together. For example, create multiple contacts in a single import rather than one-by-one via the API.
Use Webhooks for Real-Time Data
Instead of polling for updates, configure webhooks to receive real-time notifications. This eliminates unnecessary API calls.
Implement Request Queuing
Use a request queue to throttle outgoing requests and prevent bursts that could trigger rate limits.
Separate API Keys by Service
Create separate API keys for different services or applications. Each key has its own rate limit quota.
Need Higher Limits?
Enterprise customers can request increased rate limits. Contact our sales team at sales@flametalk.ai to discuss your requirements.