Rate Limiting

Understanding API rate limits and how to handle them

The PartsSource APIs implement rate limiting to ensure fair usage and system stability. Understanding these limits helps you design robust integrations.

---

Rate Limits

Tier	Requests/Second	Burst Limit
Standard	1,000 RPS	2,000 requests
Enterprise	Custom	Custom

Rate limits are applied per API client (identified by your client_id). Contact your account manager for enterprise tier access.

---

Rate Limit Headers

Every API response includes rate limit information in headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1634825400

Header	Description
X-RateLimit-Limit	Maximum requests allowed per second
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when the limit resets

---

Rate Limit Exceeded Response

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json

{
  "type": "https://tools.ietf.org/html/rfc6585#section-4",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Please retry after 1 second.",
  "correlationId": "0HN7QJKV3QJ8K:00000001"
}

The Retry-After header indicates how many seconds to wait before retrying.

---

Handling Rate Limits

Basic Retry Strategy

public async Task<T> ExecuteWithRateLimitRetry<T>(Func<Task<HttpResponseMessage>> request)
{
    var response = await request();

    if (response.StatusCode == HttpStatusCode.TooManyRequests)
    {
        // Get retry delay from header, default to 1 second
        var retryAfter = response.Headers.RetryAfter?.Delta
            ?? TimeSpan.FromSeconds(1);

        await Task.Delay(retryAfter);
        response = await request();
    }

    response.EnsureSuccessStatusCode();
    return await response.Content.ReadFromJsonAsync<T>();
}

Exponential Backoff

For production systems, implement exponential backoff:

public async Task<T> ExecuteWithExponentialBackoff<T>(
    Func<Task<HttpResponseMessage>> request,
    int maxRetries = 5)
{
    for (int attempt = 0; attempt < maxRetries; attempt++)
    {
        var response = await request();

        if (response.IsSuccessStatusCode)
        {
            return await response.Content.ReadFromJsonAsync<T>();
        }

        if (response.StatusCode != HttpStatusCode.TooManyRequests)
        {
            response.EnsureSuccessStatusCode(); // Throw for non-429 errors
        }

        // Exponential backoff: 1s, 2s, 4s, 8s, 16s
        var delay = TimeSpan.FromSeconds(Math.Pow(2, attempt));

        // Respect Retry-After header if provided
        if (response.Headers.RetryAfter?.Delta is TimeSpan retryAfter)
        {
            delay = retryAfter > delay ? retryAfter : delay;
        }

        await Task.Delay(delay);
    }

    throw new RateLimitExceededException("Max retries exceeded");
}

TypeScript Example

async function fetchWithRateLimitRetry<T>(
  url: string,
  options: RequestInit,
  maxRetries = 5
): Promise<T> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.ok) {
      const data = await response.json();
      return data.data as T;
    }

    if (response.status !== 429) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    // Get retry delay
    const retryAfter = response.headers.get('Retry-After');
    const baseDelay = Math.pow(2, attempt) * 1000; // Exponential backoff
    const delay = retryAfter
      ? Math.max(parseInt(retryAfter) * 1000, baseDelay)
      : baseDelay;

    console.log(`Rate limited. Retrying in ${delay}ms...`);
    await new Promise(resolve => setTimeout(resolve, delay));
  }

  throw new Error('Max retries exceeded due to rate limiting');
}

Python Example

import time
import requests

def fetch_with_rate_limit_retry(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.ok:
            return response.json()['data']

        if response.status_code != 429:
            response.raise_for_status()

        # Calculate delay with exponential backoff
        base_delay = 2 ** attempt
        retry_after = int(response.headers.get('Retry-After', 0))
        delay = max(base_delay, retry_after)

        print(f"Rate limited. Retrying in {delay}s...")
        time.sleep(delay)

    raise Exception("Max retries exceeded due to rate limiting")

---

Best Practices

1. Monitor Rate Limit Headers

Track your remaining quota proactively:

public void LogRateLimitStatus(HttpResponseMessage response)
{
    if (response.Headers.TryGetValues("X-RateLimit-Remaining", out var remaining))
    {
        var remainingCount = int.Parse(remaining.First());

        if (remainingCount < 100)
        {
            _logger.LogWarning(
                "Rate limit warning: {Remaining} requests remaining",
                remainingCount);
        }
    }
}

2. Implement Request Queuing

For high-volume operations, queue requests to stay under limits:

public class RateLimitedHttpClient
{
    private readonly SemaphoreSlim _semaphore;
    private readonly HttpClient _httpClient;
    private readonly int _requestsPerSecond;

    public RateLimitedHttpClient(HttpClient httpClient, int requestsPerSecond = 100)
    {
        _httpClient = httpClient;
        _requestsPerSecond = requestsPerSecond;
        _semaphore = new SemaphoreSlim(requestsPerSecond, requestsPerSecond);
    }

    public async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request)
    {
        await _semaphore.WaitAsync();

        try
        {
            return await _httpClient.SendAsync(request);
        }
        finally
        {
            // Release after delay to maintain rate
            _ = Task.Delay(1000).ContinueWith(_ => _semaphore.Release());
        }
    }
}

3. Cache Responses

Reduce API calls by caching frequently-accessed data:

public class CachedApiClient
{
    private readonly IMemoryCache _cache;
    private readonly HttpClient _httpClient;

    public async Task<Customer> GetCustomer(long customerId)
    {
        var cacheKey = $"customer:{customerId}";

        if (_cache.TryGetValue(cacheKey, out Customer cached))
        {
            return cached;
        }

        var response = await _httpClient.GetAsync($"/customers/lookup?customerId={customerId}");
        var customer = await response.Content.ReadFromJsonAsync<Customer>();

        _cache.Set(cacheKey, customer, TimeSpan.FromMinutes(5));
        return customer;
    }
}

4. Use Pagination Efficiently

Fetch only the data you need:

{
  "filters": {"status": "active"},
  "pagination": {
    "limit": 100,
    "offset": 0
  }
}

• Use reasonable page sizes (50-100 records)

• Filter results server-side when possible

• Don't fetch all pages if you only need the first few

5. Batch Operations

Combine multiple operations where possible to reduce total requests.

---

Troubleshooting

Consistently hitting rate limits?

1. Audit your integration - Are you making unnecessary calls?

2. Implement caching - Cache responses that don't change frequently

3. Use webhooks - If available, prefer push over polling

4. Contact support - Request enterprise tier for higher limits

Rate limit headers missing?

The headers are only present on authenticated requests. Verify you're including a valid Authorization header.

Getting 429s even with low volume?

1. Check if other applications share your credentials

2. Verify you're not making parallel requests unintentionally

3. Check for retry loops that could amplify traffic