> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joinrefine.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Rate Limits
> Understanding API rate limits and best practices
## Overview
The Refine API implements rate limiting to ensure fair usage and maintain service reliability for all users. Rate limits are applied per organization based on your subscription tier.
## Rate Limit Tiers
* **100 requests per minute**
* **1,000 requests per hour**
* **10,000 requests per day**
* **1,000 requests per minute**
* **30,000 requests per hour**
* **500,000 requests per day**
* **10,000 requests per minute**
* **Custom hourly limits**
* **No daily limits**
* **Dedicated support**
## Rate Limit Headers
Every API response includes headers that show your current rate limit status:
```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1623456789
```
| Header | Description |
| ----------------------- | -------------------------------------------------- |
| `X-RateLimit-Limit` | Maximum requests allowed in the current window |
| `X-RateLimit-Remaining` | Number of requests remaining in the current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit window resets |
## Rate Limit Response
When you exceed the rate limit, the API returns a `429 Too Many Requests` response:
```json theme={null}
{
"status": 429,
"message": "Rate limit exceeded",
"time": "2024-06-14T19:21:00Z",
"method": "GET",
"url": "/organizations/a8cd2722-1234-4567-9abc-def123456789/catalogs",
"retry_after": 30
}
```
## Grace Period
Non-Enterprise subscriptions have a rate limit grace period. If your subscription expires or you exceed your quota, the API will continue to work for a limited time before returning 401 Unauthorized errors.
## Best Practices
### 1. Implement Exponential Backoff
When you receive a 429 response, implement exponential backoff:
```python Python theme={null}
import time
import requests
def make_request_with_retry(url, headers, max_retries=3):
for attempt in range(max_retries):
response = requests.get(url, headers=headers)
if response.status_code != 429:
return response
# Exponential backoff
wait_time = 2 ** attempt
time.sleep(wait_time)
return response
```
```javascript Node.js theme={null}
async function makeRequestWithRetry(url, headers, maxRetries = 3) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
const response = await fetch(url, { headers });
if (response.status !== 429) {
return response;
}
// Exponential backoff
const waitTime = Math.pow(2, attempt) * 1000;
await new Promise(resolve => setTimeout(resolve, waitTime));
}
return response;
}
```
### 2. Cache Responses
Reduce API calls by caching responses when appropriate:
* Cache catalog listings for 5-10 minutes
* Cache product details for 1-5 minutes
* Never cache search results or recommendations
### 3. Batch Operations
Use batch endpoints when available:
* Create multiple products in a single request
* Delete multiple products in one operation
* Process updates in batches rather than individually
### 4. Monitor Usage
Track your API usage to avoid hitting limits:
```python theme={null}
remaining = int(response.headers.get('X-RateLimit-Remaining', 0))
if remaining < 100:
logger.warning(f"Low rate limit: {remaining} requests remaining")
```
## Rate Limit Optimization
Subscribe to webhooks instead of polling for updates
Cache frequently accessed data to reduce API calls
Combine multiple operations into single requests
Apply filters to reduce response size and processing time
## Need Higher Limits?
If you're consistently hitting rate limits, consider:
1. **Upgrading your plan** - Higher tiers offer increased limits
2. **Contacting sales** - Enterprise plans can be customized
3. **Optimizing your integration** - Our team can help identify optimization opportunities
Discuss custom rate limits for your use case