Rate Limits

The Chariow API implements rate limiting to ensure fair usage and maintain service quality for all users.

Default Limits

Requests	Limit	Counted per
All public API endpoints except checkout	100 requests per minute	API key
`POST /v1/checkout`	100 requests per minute	API key, in a separate counter
Requests without a well-formed API key	100 requests per minute	IP address

Each API key has its own counters, so one integration cannot slow down another behind the same IP address. Checkout has its own counter so that an integration syncing sales or products can never use up the key’s budget and stop buyers from paying. A key can therefore send up to 100 checkout requests and 100 other requests in the same minute. Every request counts towards the limit, including requests rejected with 401 or 403.

The MCP server has its own limits: 60 requests per minute per MCP connection. See MCP tools.

Rate Limit Headers

Every rate-limited response includes headers indicating your current status:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 98

When you exceed the limit, the 429 response adds two more headers:

HTTP/1.1 429 Too Many Requests
Retry-After: 42
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1760000000

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the window
`X-RateLimit-Remaining`	Requests remaining in the current window
`Retry-After`	Seconds to wait before retrying (only on `429`)
`X-RateLimit-Reset`	Unix timestamp when the limit resets (only on `429`)

Rate Limit Exceeded

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

{
  "message": "Too Many Attempts.",
  "errors": []
}

Wait for the number of seconds given in the Retry-After header before sending the next request.

Handling Rate Limits

Exponential Backoff

Implement exponential backoff to gracefully handle rate limits, and never retry before Retry-After has elapsed:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = Number(response.headers.get('Retry-After')) || 60;
      const delay = Math.max(retryAfter * 1000, Math.pow(2, attempt) * 1000);

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

    return response;
  }

  throw new Error('Max retries exceeded');
}

Request Batching

Batch multiple operations to reduce request count:

// Instead of making 100 individual requests
for (const customerId of customerIds) {
  await getCustomer(customerId); // 100 requests
}

// Use pagination to get multiple at once
const customers = await listCustomers({ per_page: 100 }); // 1 request

Caching

Cache responses to avoid unnecessary requests:

const cache = new Map();
const CACHE_TTL = 60000; // 1 minute

async function getCachedCustomer(customerId) {
  const cached = cache.get(customerId);

  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }

  const response = await fetch(`/v1/customers/${customerId}`, {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });

  const data = await response.json();
  cache.set(customerId, { data, timestamp: Date.now() });

  return data;
}

Increasing Limits

If you need higher rate limits:

Optimise Usage - Review your implementation: pagination, caching and webhooks remove most polling
Contact Support - Explain your use case and expected volume

Contact support@chariow.com to discuss higher rate limits for your use case.

Best Practices

Monitor Your Usage

Track rate limit headers to understand your usage patterns and adjust accordingly.

Use Webhooks

Instead of polling for changes, use webhooks to receive real-time notifications.

Implement Queuing

Queue requests and process them at a controlled rate to avoid bursts.

Cache Aggressively

Cache data that doesn’t change frequently to reduce API calls.

Introduction

Guides

MCP Integration

n8n Integration

Resources

Default Limits

Rate Limit Headers

Rate Limit Exceeded

Handling Rate Limits

Exponential Backoff

Request Batching

Caching

Increasing Limits

Best Practices

​Default Limits

​Rate Limit Headers

​Rate Limit Exceeded

​Handling Rate Limits

​Exponential Backoff

​Request Batching

​Caching

​Increasing Limits

​Best Practices

Default Limits

Rate Limit Headers

Rate Limit Exceeded

Handling Rate Limits

Exponential Backoff

Request Batching

Caching

Increasing Limits

Best Practices