Skip to main content

​
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
HeaderDescription
X-RateLimit-LimitMaximum requests allowed in the current window
X-RateLimit-RemainingNumber of requests remaining in the current window
X-RateLimit-ResetUnix 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

​
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:
  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

Contact Sales

Discuss custom rate limits for your use case