Rate Limiting

Understand Sematryx's rate limits and learn how to handle them gracefully in your applications.

Overview

Sematryx implements rate limiting to ensure fair usage and system stability. Rate limits vary by plan:

Free Plan: 100 requests per hour
Pro Plan: 1,000 requests per hour
Enterprise Plan: 10,000+ requests per hour (custom limits available)

Rate Limit Headers

Every API response includes rate limit information in the headers:

Rate limit response headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1640995200

Header Fields

X-RateLimit-Limit: Maximum number of 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

Handling Rate Limits

When you exceed the rate limit, you'll receive a 429 Too Many Requests status code. Always check rate limit headers and implement retry logic with appropriate backoff.

Python Example

Rate limit handling in Python

import time
import requests

def make_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers)
        
        if response.status_code == 429:
            reset_time = int(response.headers.get('X-RateLimit-Reset', 0))
            wait_time = max(reset_time - time.time(), 1)
            print(f'Rate limit exceeded. Waiting {wait_time} seconds...')
            time.sleep(wait_time)
            continue
        
        return response
    
    raise Exception('Max retries exceeded')

JavaScript Example

Rate limit handling in JavaScript

async function makeRequestWithRetry(url, headers, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, { method: 'POST', headers })
    
    if (response.status === 429) {
      const resetTime = parseInt(response.headers.get('X-RateLimit-Reset') || '0')
      const waitTime = Math.max(resetTime - Date.now() / 1000, 1)
      console.log(`Rate limit exceeded. Waiting ${waitTime} seconds...`)
      await new Promise(resolve => setTimeout(resolve, waitTime * 1000))
      continue
    }
    
    return response
  }
  
  throw new Error('Max retries exceeded')
}

Exponential Backoff

For more robust rate limit handling, implement exponential backoff with jitter:

Exponential backoff implementation

import time
import random

def exponential_backoff(attempt, base_delay=1, max_delay=60):
    """Calculate exponential backoff delay with jitter"""
    delay = min(base_delay * (2 ** attempt), max_delay)
    jitter = random.uniform(0, delay * 0.1)
    return delay + jitter

# Usage
for attempt in range(max_retries):
    try:
        response = make_request()
        break
    except RateLimitError:
        wait_time = exponential_backoff(attempt)
        time.sleep(wait_time)

Benefits

Prevents thundering herd problems
Reduces server load during high traffic
More efficient use of available rate limit
Jitter prevents synchronized retries

Best Practices

✅ Do

Monitor rate limit headers on every request
Implement retry logic with exponential backoff
Cache responses when possible to reduce API calls
Use webhooks instead of polling when available
Batch requests when possible
Respect the reset time from X-RateLimit-Reset header

❌ Don't

Ignore 429 status codes
Retry immediately without waiting
Make unnecessary requests
Poll endpoints when webhooks are available
Exceed rate limits intentionally

Rate Limit Windows

Rate limits are calculated on a rolling window basis. The window resets at the time specified inX-RateLimit-Reset.

Example

If you have a limit of 1,000 requests per hour and make 50 requests at 10:00 AM, you'll have 950 requests remaining. At 11:00 AM, your limit resets to 1,000 requests.

The reset time is always provided in the response headers, so you can plan your requests accordingly.

Increasing Rate Limits

If you need higher rate limits, consider:

Upgrade Your Plan

Pro and Enterprise plans offer significantly higher rate limits.View plans

Contact Support

Enterprise customers can request custom rate limits based on their usage patterns and requirements.