Docs/Rate Limits

Rate Limits

Understand API rate limits and how to handle them gracefully in your application.

Rate Limits by Plan

Plan	Requests/min	Requests/day	Burst Limit
Free	10	100	20
Pro	100	10,000	200
Enterprise	1,000	Unlimited	2,000

Burst limit is the maximum requests allowed in a 1-second window.

Rate Limit Headers

Every API response includes headers showing your current rate limit status:

http

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1732624560

Header	Description
X-RateLimit-Limit	Maximum requests per minute for your plan
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when limit resets

Rate Limited Response

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

http

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

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please retry after 30 seconds."
  }
}

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

Handling Rate Limits

Implement exponential backoff when you encounter rate limits:

javascript

1400">async 400">function fetchWithRateLimitHandling(url, options, maxRetries = 3) {
2  for (400">let attempt = 0; attempt < maxRetries; attempt++) {
3    400">const response = 400">await fetch(url, options);
4 
5    500">// Track remaining requests
6    400">const remaining = response.headers.get(400">&#039;X-RateLimit-Remaining&#039;);
7    400">if (remaining && parseInt(remaining) < 10) {
8      console.warn(400">`Rate limit warning: ${remaining} requests remaining`);
9    }
10 
11    500">// Handle rate limit
12    400">if (response.status === 429) {
13      400">const retryAfter = response.headers.get(400">&#039;Retry-After&#039;);
14      400">const waitTime = retryAfter ? parseInt(retryAfter) * 1000 : 1000 * Math.pow(2, attempt);
15 
16      console.log(400">`Rate limited. Waiting ${waitTime}ms before retry...`);
17      400">await 400">new Promise(resolve => setTimeout(resolve, waitTime));
18      continue;
19    }
20 
21    400">return response;
22  }
23 
24  400">throw 400">new Error(400">&#039;Max retries exceeded due to rate limiting&#039;);
25}

Best Practices

Implement caching

Cache responses where appropriate to reduce API calls. Transaction statuses that are "completed" or "failed" won't change.

Use webhooks instead of polling

Instead of repeatedly checking transaction status, use webhooks to receive real-time notifications when status changes.

Batch requests where possible

When listing transactions, request larger page sizes (up to 100) to reduce the number of API calls needed.

Monitor your usage

Check the X-RateLimit-Remaining header and slow down requests proactively before hitting the limit.

Use exponential backoff

When retrying after rate limits, use exponential backoff with jitter to avoid thundering herd problems.

Transaction Limits

In addition to API rate limits, there are limits on transaction amounts:

Plan	Min Transaction	Max Transaction	Daily Limit
Free	$10	$500	$1,000
Pro	$10	$10,000	$50,000
Enterprise	$1	$100,000+	Custom

Increasing Your Limits

If you need higher limits:

Upgrade your plan - Pro and Enterprise plans have significantly higher limits
Contact sales - For Enterprise plans with custom limits,contact our sales team
Request temporary increase - For expected traffic spikes, contact support in advance

SDK Rate Limit Handling

Our SDK automatically handles rate limits with retry logic:

javascript

400">import { Web3Pay } 400">from 400">&#039;@web3pay/sdk&#039;;

400">const client = 400">new Web3Pay({
  apiKey: 400">&#039;wp3_live_sk_...&#039;,
  500">// Configure retry behavior
  maxRetries: 3,           500">// Max retry attempts (400">default: 3)
  retryDelay: 1000,        500">// Initial retry delay in ms (400">default: 1000)
  retryOnRateLimit: 400">true   500">// Auto-retry on 429 (400">default: 400">true)
});

500">// SDK will automatically retry with backoff
400">const session = 400">await client.createSession({...});