Skip to main content

Rate Limiting Guide

Understand and manage API rate limits for optimal performance.

Account limits​

YODI enforces request limits server-side. The configured limit can vary by account and plan, and plan terms can change. Do not copy historic plan limits or prices from this guide. Read the currently published plan terms in the live plan catalog; account-specific limits shown in the Console remain authoritative for your account.

Do not assume every API response contains X-RateLimit-* headers. On a throttling rejection, use the standard error envelope and honor Retry-After or meta.retry_after_ms when the server provides them.

Handling Rate Limit Errors​

429 Too Many Requests​

When you exceed the rate limit, you'll receive a 429 status code:

interface RateLimitErrorEnvelope {
  error: true;
  status: 429;
  message: "RATE_LIMIT_EXCEEDED";
  data: null;
  meta: {
    request_id: string;
    served_at: string;
    retry_after_ms?: number;
  };
}

How to Handle It​

  1. Check the response header for Retry-After value
  2. Wait the specified time before retrying
  3. Use exponential backoff for multiple retries

Exponential Backoff Example (Python)​

import time
import requests

def retry_with_backoff(url, headers, data, max_retries=5):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=data)
        
        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 2 ** attempt))
            print(f"Rate limited. Waiting {retry_after}s...")
            time.sleep(retry_after)
            continue
        
        return response
    
    raise Exception("Max retries exceeded")

Best Practices​

1. Honor server retry guidance​

response = requests.get(url, headers=headers)

# Do not retry before the server-provided delay. If no delay is present,
# use bounded exponential backoff with jitter for this idempotent read.
retry_after = response.headers.get('Retry-After')

2. Batch Requests When Possible​

Instead of making individual requests:

#  Bad - Multiple requests
for text in texts:
    response = requests.post(url, data={'text': text})

#  Good - Batch requests
batch = [{'text': t} for t in texts]
response = requests.post(url, data={'batch': batch})

3. Cache Results​

from functools import lru_cache

@lru_cache(maxsize=128)
def translate_cached(text, language):
    return api.translate(text, language)

4. Implement Queuing​

For high-volume applications, use a queue system:

from queue import Queue
import threading

class APIQueue:
    def __init__(self, rate_limit_per_sec=5):
        self.queue = Queue()
        self.rate_limit = rate_limit_per_sec
        self.worker = threading.Thread(target=self._process)
        self.worker.daemon = True
        self.worker.start()
    
    def _process(self):
        last_request = 0
        while True:
            item = self.queue.get()
            # Ensure minimum time between requests
            time.sleep(max(0, last_request + (1/self.rate_limit) - time.time()))
            self._make_request(item)
            last_request = time.time()

Review available plans​

If your account needs a different limit, review currently published options in the live plan catalog or contact YODI through the Console. Do not assume a plan change is complete until the backend confirms the entitlement.

Troubleshooting​

Q: Why am I getting 429 errors?​

A: You've exceeded the rate limit for your plan. Either:

  1. Wait before making more requests
  2. Upgrade to a higher plan
  3. Implement request batching

Q: Can I request a higher rate limit?​

A: Check the currently published plan catalog or contact YODI through the Console. Higher limits are not guaranteed by a plan name alone.

Q: Does the rate limit reset hourly or daily?​

A: Follow the Retry-After response header or meta.retry_after_ms when provided. The exact enforcement window is server-controlled and is not inferred from a plan label.

Next Steps​