Rate Limits

API rate limiting policies and best practices.

Rate Limit Overview

To ensure API availability and prevent abuse, AuxVault enforces rate limits:

Rate Limit Headers

Every API response includes rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1706454600

Rate Limit Exceeded

When you exceed the rate limit:

Response:

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

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "details": {
      "retryAfter": 60,
      "limit": 100,
      "resetAt": "2026-01-28T13:30:00Z"
    }
  }
}

Best Practices

✅ Implement Exponential Backoff

async function makeRequestWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.code === 'RATE_LIMIT_EXCEEDED' && i < maxRetries - 1) {
        const delay = Math.min(1000 * Math.pow(2, i), 10000);
        await sleep(delay);
        continue;
      }
      throw error;
    }
  }
}

// Usage
const transaction = await makeRequestWithRetry(() =>
  client.transactions.create({...})
);

✅ Check Headers Before Retry

function shouldRetry(response) {
  const remaining = parseInt(response.headers['x-ratelimit-remaining']);
  const resetTime = parseInt(response.headers['x-ratelimit-reset']);
  
  if (remaining === 0) {
    const waitTime = (resetTime * 1000) - Date.now();
    console.log(`Rate limit hit. Waiting ${waitTime}ms`);
    return { shouldRetry: true, waitTime };
  }
  
  return { shouldRetry: false };
}

✅ Batch Requests

Instead of making 100 individual requests:

// ❌ BAD: 100 API calls
for (const txn of transactions) {
  await client.transactions.get(txn.id);
}

// ✅ GOOD: 1 API call
const txns = await client.transactions.list({
  ids: transactions.map(t => t.id)
});

✅ Cache Responses

const cache = new Map();

async function getTransaction(id) {
  if (cache.has(id)) {
    return cache.get(id);
  }
  
  const txn = await client.transactions.get(id);
  cache.set(id, txn);
  
  // Cache for 5 minutes
  setTimeout(() => cache.delete(id), 5 * 60 * 1000);
  
  return txn;
}

✅ Use Webhooks Instead of Polling

// ❌ BAD: Poll every second (3600 requests/hour)
setInterval(async () => {
  const status = await client.transactions.get(txnId);
  if (status === 'approved') {
    processTransaction();
  }
}, 1000);

// ✅ GOOD: Use webhooks (0 polling requests)
app.post('/webhook', (req, res) => {
  if (req.body.type === 'transaction.approved') {
    processTransaction(req.body.data);
  }
  res.sendStatus(200);
});

Rate Limit by Endpoint

Some endpoints have different limits:

Monitoring Rate Limits

Check Current Usage

curl https://api.auxvault.com/api/v1/rate-limit/status \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Response:

{
  "success": true,
  "data": {
    "limit": 100,
    "remaining": 85,
    "resetAt": "2026-01-28T13:30:00Z",
    "usage": {
      "minute": 15,
      "hour": 250,
      "day": 3500
    }
  }
}

Increasing Rate Limits

Need higher limits? Options:

1. Upgrade your plan - Professional or Enterprise tiers
2. Contact support - Custom limits for high-volume merchants
3. Optimize your integration - Reduce unnecessary calls

Contact: support@auxvault.com

Testing Rate Limits

In sandbox, trigger rate limit for testing:

# Make 101 rapid requests
for i in {1..101}; do
  curl https://sandbox-api.auxvault.com/api/v1/transactions/test_123 &
done
wait

# 101st request should return 429

Next Steps

• Error handling →
• Webhooks guide →
• API reference →

Need help? Contact support@auxvault.com