Rate Limiting

The RizPay API uses rate limiting to ensure fair usage and system stability. Understanding rate limits helps you build reliable integrations.

How It Works

Rate limits are enforced per API key on a rolling 1-minute window. Each API key has a maximum number of requests allowed per minute based on your account tier.

Rate Limit Tiers

Your tier is automatically determined by your account level. Contact support to discuss higher limits for enterprise needs.

Response Headers

Every API response includes rate limit headers:

Example response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705312860

When You Hit the Limit

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

{
  "status": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry after 45 seconds."
  },
  "data": null
}

The response includes a Retry-After header indicating how many seconds to wait:

Retry-After: 45

Handling Rate Limits

Basic Retry Logic

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

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get("Retry-After") || "60");
      console.log(`Rate limited. Waiting ${retryAfter} seconds...`);
      await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
      continue;
    }

    return response;
  }

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

Proactive Rate Limit Checking

async function makeRequest(url, options) {
  const response = await fetch(url, options);

  const remaining = parseInt(response.headers.get("X-RateLimit-Remaining"));
  const resetTime = parseInt(response.headers.get("X-RateLimit-Reset"));

  if (remaining < 5) {
    const waitTime = resetTime * 1000 - Date.now();
    console.log(
      `Low on requests. ${remaining} remaining. Resets in ${waitTime}ms`
    );
  }

  return response;
}

Best Practices

1. Monitor rate limit headers - Track remaining requests proactively
2. Implement exponential backoff - Don't hammer the API when rate limited
3. Cache responses - Reduce unnecessary API calls for data that doesn't change often
4. Batch operations - Combine multiple operations where possible
5. Use webhooks - Instead of polling for status updates, use webhooks

Sandbox Rate Limits

The sandbox environment has a more lenient rate limit of 60 requests per minute for all accounts. This allows thorough testing without worrying about limits.

Next Steps

• Pagination - Navigate large result sets
• Error Handling - Handle all error types