Rate Limits

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

Free Tier

100 requests per minute
1,000 requests per hour
10,000 requests per day

Professional

1,000 requests per minute
30,000 requests per hour
500,000 requests per day

Enterprise

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:

{
  "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:

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

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:

remaining = int(response.headers.get('X-RateLimit-Remaining', 0))
if remaining < 100:
    logger.warning(f"Low rate limit: {remaining} requests remaining")

Rate Limit Optimization

Use Webhooks

Subscribe to webhooks instead of polling for updates

Implement Caching

Cache frequently accessed data to reduce API calls

Batch Requests

Combine multiple operations into single requests

Use Filters

Apply filters to reduce response size and processing time

Need Higher Limits?

If you’re consistently hitting rate limits, consider:

Upgrading your plan - Higher tiers offer increased limits
Contacting sales - Enterprise plans can be customized
Optimizing your integration - Our team can help identify optimization opportunities

Contact Sales

Discuss custom rate limits for your use case

Getting Started

Catalog Operations

Product Operations

Search

Recommendations

Catalog Operations

Product Operations

Search

Recommendations

Overview

Rate Limit Tiers

Rate Limit Headers

Rate Limit Response

Grace Period

Best Practices

1. Implement Exponential Backoff

2. Cache Responses

3. Batch Operations

4. Monitor Usage

Rate Limit Optimization

Use Webhooks

Implement Caching

Batch Requests

Use Filters

Need Higher Limits?

Contact Sales

​Overview

​Rate Limit Tiers

​Rate Limit Headers

​Rate Limit Response

​Grace Period

​Best Practices

​1. Implement Exponential Backoff

​2. Cache Responses

​3. Batch Operations

​4. Monitor Usage

​Rate Limit Optimization

Use Webhooks

Implement Caching

Batch Requests

Use Filters

​Need Higher Limits?

Contact Sales

Overview

Rate Limit Tiers

Rate Limit Headers

Rate Limit Response

Grace Period

Best Practices

1. Implement Exponential Backoff

2. Cache Responses

3. Batch Operations

4. Monitor Usage

Rate Limit Optimization

Need Higher Limits?