Rate Limiting Guide

Overview

Rate limiting protects our API infrastructure by controlling how many requests you can make within specific time periods. Think of it like having three different speed limits on the same road - you need to respect all of them to keep moving smoothly. Our system uses three-tier rate limiting to ensure fair usage and optimal performance for all developers:

Per-Second Limits

Prevents burst traffic spikes

Per-Minute Limits

Controls sustained request rates

Daily Limits

Manages overall daily usage

How Rate Limiting Works

Three-Tier Protection

Every API request must pass through all three rate limiting tiers:

Second-level: Allows quick bursts of requests (typically 5-50 per second)
Minute-level: Permits sustained usage (typically 100-3000 per minute)
Daily-level: Sets overall usage bounds (typically 10,000-100,000 per day)

Your specific limits depend on your TitanX plan. Use the /api/public/quota endpoint to see your current limits.

Fixed Time Windows

Our rate limits use fixed time windows that reset at exact intervals:

Per-Second
Per-Minute
Daily

Resets every second at the exact second boundary.Example: If it’s currently 14:23:45.750, your second quota will reset at 14:23:46.000

Resets every minute at the exact minute boundary.Example: If it’s currently 14:23:45, your minute quota will reset at 14:24:00

Resets every day at midnight UTC.Example: If it’s currently 2024-01-15 14:23:45, your daily quota will reset at 2024-01-16 00:00:00 UTC

How Quotas Are Consumed

Each successful API request consumes 1 quota from all three tiers simultaneously. Failed requests (4xx/5xx errors) still consume quota to prevent abuse.

If ANY tier is exceeded, your request will be blocked with a 429 Too Many Requests response, even if the other tiers have remaining quota.

Rate Limit Headers

Every API response includes detailed information about your current rate limit status through HTTP headers:

Complete Headers Reference

Header	Description	Example
`X-RateLimit-Limit-Second`	Maximum requests allowed per second	`10`
`X-RateLimit-Remaining-Second`	Remaining requests this second	`7`
`X-RateLimit-Reset-Second`	When second quota resets (Unix timestamp)	`1704110401`
`X-RateLimit-Limit-Minute`	Maximum requests allowed per minute	`300`
`X-RateLimit-Remaining-Minute`	Remaining requests this minute	`287`
`X-RateLimit-Reset-Minute`	When minute quota resets (Unix timestamp)	`1704110460`
`X-RateLimit-Limit-Day`	Maximum requests allowed per day	`50000`
`X-RateLimit-Remaining-Day`	Remaining requests today	`49713`
`X-RateLimit-Reset-Day`	When daily quota resets (Unix timestamp)	`1704153600`

Special Headers

When you’re rate limited, additional headers help you retry effectively:

Header	Description	Example
`Retry-After`	Seconds to wait before retrying	`1`

Convert Unix timestamps to readable dates: new Date(timestamp * 1000) in JavaScript

Example Response Headers

HTTP/1.1 200 OK
X-RateLimit-Limit-Second: 10
X-RateLimit-Remaining-Second: 7
X-RateLimit-Reset-Second: 1704110401
X-RateLimit-Limit-Minute: 300
X-RateLimit-Remaining-Minute: 287
X-RateLimit-Reset-Minute: 1704110460
X-RateLimit-Limit-Day: 50000
X-RateLimit-Remaining-Day: 49713
X-RateLimit-Reset-Day: 1704153600

Checking Your Quota

Use the /api/public/quota endpoint to check your current limits without consuming quota:

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     https://app.titanx.io/api/public/quota

const response = await fetch('https://app.titanx.io/api/public/quota', {
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  }
});

const data = await response.json();
console.log('Rate limit status:', data);

import requests

headers = {'Authorization': 'Bearer YOUR_JWT_TOKEN'}
response = requests.get('https://app.titanx.io/api/public/quota', headers=headers)
quota_info = response.json()
print(f"Rate limit status: {quota_info}")

Handling Rate Limits

When You Hit a Limit

When any rate limit is exceeded, you’ll receive a 429 Too Many Requests response:

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Rate limit exceeded for second tier.",
  "tier": "second",
  "retryAfter": 1704110401
}

Best Practices for Retries

Check the Retry-After Header

Always respect the Retry-After header value before making another request.

Implement Exponential Backoff

If you don’t receive a Retry-After header, use exponential backoff starting with 1 second.

Monitor All Tiers

Watch the remaining quota for all three tiers, not just the one that was exceeded.

Spread Your Requests

Avoid sending bursts of requests. Distribute them evenly across time.

Example Retry Logic

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After');
        const waitTime = retryAfter ? parseInt(retryAfter) * 1000 : Math.pow(2, attempt) * 1000;
        
        console.log(`Rate limited. Waiting ${waitTime}ms before retry ${attempt}/${maxRetries}`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }
      
      return response;
    } catch (error) {
      if (attempt === maxRetries) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
    }
  }
}

import time
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

def make_request_with_retry(url, headers, max_retries=3):
    for attempt in range(1, max_retries + 1):
        try:
            response = requests.get(url, headers=headers)
            
            if response.status_code == 429:
                retry_after = response.headers.get('Retry-After')
                wait_time = int(retry_after) if retry_after else 2 ** attempt
                
                print(f"Rate limited. Waiting {wait_time}s before retry {attempt}/{max_retries}")
                time.sleep(wait_time)
                continue
                
            return response
        except requests.RequestException as e:
            if attempt == max_retries:
                raise e
            time.sleep(2 ** attempt)

Monitoring Your Usage

Proactively monitor your rate limits to avoid hitting them:

// Check if you're approaching any limits
function checkRateLimitStatus(headers) {
  const secondRemaining = parseInt(headers.get('X-RateLimit-Remaining-Second'));
  const minuteRemaining = parseInt(headers.get('X-RateLimit-Remaining-Minute'));
  const dayRemaining = parseInt(headers.get('X-RateLimit-Remaining-Day'));
  
  // Warn when approaching limits
  if (secondRemaining <= 1) {
    console.warn('⚠️ Very low second-tier quota remaining');
  }
  if (minuteRemaining <= 10) {
    console.warn('⚠️ Low minute-tier quota remaining');
  }
  if (dayRemaining <= 100) {
    console.warn('⚠️ Low daily quota remaining');
  }
}

Common Integration Patterns

Batch Processing

When processing multiple items, respect rate limits:

async function processBatch(items, apiCall) {
  const results = [];
  
  for (const item of items) {
    const response = await makeRequestWithRetry(apiCall, item);
    results.push(response);
    
    // Check remaining quotas and pace accordingly
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining-Second'));
    if (remaining <= 2) {
      // Slow down when approaching limits
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
  }
  
  return results;
}

Real-time Applications

For real-time apps, check quotas before making requests:

async function smartApiCall(endpoint, payload) {
  // Check quota first
  const quotaResponse = await fetch('/api/public/quota', { 
    headers: { 'Authorization': `Bearer ${token}` }
  });
  
  const secondRemaining = parseInt(quotaResponse.headers.get('X-RateLimit-Remaining-Second'));
  
  if (secondRemaining <= 1) {
    console.log('Quota low, waiting for reset...');
    const resetTime = parseInt(quotaResponse.headers.get('X-RateLimit-Reset-Second'));
    const waitTime = (resetTime * 1000) - Date.now();
    await new Promise(resolve => setTimeout(resolve, waitTime));
  }
  
  return fetch(endpoint, {
    method: 'POST',
    body: JSON.stringify(payload),
    headers: { 'Authorization': `Bearer ${token}` }
  });
}

Troubleshooting

Common Issues

Getting 429 errors despite low usage

Cause: Sending requests in tight loops can exceed per-second limits even with low overall volume.Solution: Add small delays between requests or implement proper retry logic.

Inconsistent rate limit behavior

Cause: Rate limits are enforced per client ID. Using multiple API keys may have different limits.Solution: Check your client configuration and ensure you’re using the correct authentication token.

Daily limits resetting at unexpected times

Cause: Daily limits reset at midnight UTC, which may differ from your local timezone.Solution: Convert the X-RateLimit-Reset-Day timestamp to your local timezone to see the actual reset time.

Getting Help

If you’re experiencing persistent rate limiting issues:

Check your plan limits in the TitanX dashboard
Review your request patterns for burst behavior
Verify your authentication tokens are correct
Contact support with your client ID and example requests

Need higher limits? Upgrade your plan in the TitanX dashboard or contact our sales team for enterprise options.

Get Started

Rate Limits

Webhooks

Overview

Per-Second Limits

Per-Minute Limits

Daily Limits

How Rate Limiting Works

Three-Tier Protection

Fixed Time Windows

How Quotas Are Consumed

Rate Limit Headers

Complete Headers Reference

Special Headers

Example Response Headers

Checking Your Quota

Handling Rate Limits

When You Hit a Limit

Best Practices for Retries

Example Retry Logic

Monitoring Your Usage

Common Integration Patterns

Batch Processing

Real-time Applications

Troubleshooting

Common Issues

Getting Help

​Overview

Per-Second Limits

Per-Minute Limits

Daily Limits

​How Rate Limiting Works

​Three-Tier Protection

​Fixed Time Windows

​How Quotas Are Consumed

​Rate Limit Headers

​Complete Headers Reference

​Special Headers

​Example Response Headers

​Checking Your Quota

​Handling Rate Limits

​When You Hit a Limit

​Best Practices for Retries

​Example Retry Logic

​Monitoring Your Usage

​Common Integration Patterns

​Batch Processing

​Real-time Applications

​Troubleshooting

​Common Issues

​Getting Help

Overview

How Rate Limiting Works

Three-Tier Protection

Fixed Time Windows

How Quotas Are Consumed

Rate Limit Headers

Complete Headers Reference

Special Headers

Example Response Headers

Checking Your Quota

Handling Rate Limits

When You Hit a Limit

Best Practices for Retries

Example Retry Logic

Monitoring Your Usage

Common Integration Patterns

Batch Processing

Real-time Applications

Troubleshooting

Common Issues

Getting Help