API Reference

API Rate Limits

Overview

Rate limits define how many API requests a client can make within a specific time window. They control the frequency of API calls, not the total amount of data processed over time. When the allowed limit is exceeded, the API responds with an error code of 429 and an error message of Too many requests. Try again after 1 min. until the limit resets.

Why Rate Limits Exist

1. Protect Against Abuse: Prevents malicious or misconfigured clients from overwhelming the system, reducing the risk of service disruptions and DDoS attacks.

2. Ensure Fair Access: Controls resource allocation so one client doesn’t consume a disproportionate amount of resources, maintaining stable performance for all users.

3. Maintain System Stability: Helps smooth traffic patterns and maintain consistent, reliable performance across shared infrastructure.

How Rate Limits Are Enforced

Rate limits are enforced per API key, which means:

Each API key has its own independent rate limit
All requests using the same API key count toward the same limit
Multiple applications/services sharing the same API key share the same quota
Separate API keys have separate rate limits

The table below shows the limits applied per API key:

Endpoint	Rate Limit	Time Window
Upload	20	per minute
Convert	100	per minute
Bulk Convert	100	per minute
Status	100	per minute
Result	100	per minute

Best Practices

1. Implement Exponential Backoff

When you receive a rate limit error (429):

Wait for a short time before retrying
If the retry fails, wait longer and try again
Keep increasing the delay until success or maximum retries reached
Add random jitter to prevent synchronized retries

Important: Failed requests still count toward your rate limit, so repeatedly retrying without delay will not solve the problem.

Below is an example solution for Python that uses exponential backoff:

import asyncio
import random
import aiohttp
from typing import Dict, Any

API_URL = "Endpoint_URL"
X_CLIENT_ID = "your-client-id"
X_CLIENT_SECRET = "your-client-secret"

def retry_with_exponential_backoff_async(
    initial_delay: float = 1.0,
    exponential_base: float = 2.0,
    jitter: bool = True,
    max_retries: int = 10,
    retry_on_status: tuple = (429,),
):
    """Async retry decorator with exponential backoff based on status codes."""
    
    def decorator(func):
        async def wrapper(*args, **kwargs):
            num_retries = 0
            delay = initial_delay
            
            while True:
                result = await func(*args, **kwargs)
                
                # Check if status code should trigger retry
                if result in retry_on_status:
                    num_retries += 1
                    
                    # Max retries exceeded
                    if num_retries > max_retries:
                        print(f"Maximum retries ({max_retries}) exceeded for status {result}")
                        return result
                    
                    # Calculate exponential backoff with jitter
                    delay *= exponential_base * (1 + jitter * random.random())
                    
                    print(f"Status {result}. Retrying in {delay:.2f}s... (Attempt {num_retries}/{max_retries})")
                    await asyncio.sleep(delay)
                else:
                    # Success or non-retryable status
                    return result
        
        return wrapper
    return decorator

@retry_with_exponential_backoff_async(
    initial_delay=1.0,
    exponential_base=2.0,
    jitter=True,
    max_retries=10,
    retry_on_status=(429,)
)
async def send_request(request_id: int, session: aiohttp.ClientSession, payload: Dict[str, Any]) -> int:
    """Send an async request to test rate limits.
    
    Args:
        request_id: Unique identifier for this request
        session: aiohttp ClientSession for connection pooling
        payload: JSON payload to send in the POST request
        
    Returns:
        HTTP status code
    """
    
    headers = {
        "Content-Type": "application/json",
        "X-Client-Id": X_CLIENT_ID,
        "X-Client-Secret": X_CLIENT_SECRET
    }
    
    result_code = 0
    
    try:
        async with session.post(
            API_URL,
            headers=headers,
            json=payload,
            timeout=aiohttp.ClientTimeout(total=3600)
        ) as response:
            
            result_code = response.status

            # CASE 1: Rate Limit Hit
            if response.status == 429:
                response_text = await response.text()
                print(f"Req {request_id}: 429 RATE LIMITED")
                print(f"Response body: {response_text}")
            
            else:
                pass
    
    except Exception as e:
        print(f"Req {request_id}: Unexpected Error - {str(e)}")
    
    return result_code

async def run_concurrent(payloads: list[Dict[str, Any]]):    

    async with aiohttp.ClientSession() as session:
        # Create all tasks at once
        tasks = [
            send_request(request_id, session, payload) 
            for request_id, payload in enumerate(payloads)
        ]
        
        # Run all concurrently
        await asyncio.gather(*tasks)

async def main():
    """Main function to choose execution mode."""
    
    #List of Payload Dictionaries
    payloads = [] 
    
    await run_concurrent(payloads)

if __name__ == "__main__":
    asyncio.run(main())

2. Use Separate API Keys

If different applications or services require independent rate limits, generate and use separate API keys to avoid shared throttling.

3. Using Bulk Convert for Higher Throughput

If the Upload endpoint’s rate limit (20 requests/min) is too restrictive for your use case, consider using the Bulk Convert endpoint instead. This endpoint is specifically designed for high-volume workflows and bulk data imports as it accepts up to 30 pre-signed URLs in a single request and is subject to a 100 requests/min rate limit.

4. Monitor Request Patterns

Regularly track your request patterns to identify bottlenecks or spikes. If your use case requires higher limits, contact support to discuss an appropriate rate limit increase.