Request Limits

Learn about rate limiting and how to manage API usage

Weight System

MintMove API uses a weight-based rate limiting system. Each endpoint has an associated weight, and you have a limited number of weight units available per time period.

Rate Limit

250 units per minute

Your weight allowance resets every 60 seconds

Endpoint Weights

Endpoint	Method	Weight
/v1/order/create	POST	50 units
/v1/rate	GET	1 unit
/v1/currencies	GET	1 unit
/v1/order/{id}	GET	1 unit
/v1/order/{id}/emergency	POST	1 unit
/v1/order/{id}/qr	GET	1 unit

Note: Creating orders consumes significantly more weight (50 units) due to the computational resources required for order processing and address generation.

Rate Limit Headers

Every API response includes headers that show your current rate limit status:

Header	Description
X-RateLimit-Limit	Total weight units per minute (250)
X-RateLimit-Remaining	Remaining weight units in current window
X-RateLimit-Reset	Unix timestamp when the limit resets

HTTP 429 Response

When you exceed the rate limit, the API returns a 429 Too Many Requests status code.

Error Response

{
  "error": true,
  "error_code": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded. Please try again later.",
  "retry_after": 45
}

The retry_after field indicates how many seconds you should wait before making another request.

Burst Protection

In addition to the per-minute limit, burst protection prevents sudden spikes in API usage. This ensures fair resource allocation and system stability.

•Burst Limit: Maximum 10 requests per second, regardless of weight
•Sliding Window: Limits are enforced using a sliding window algorithm
•Automatic Recovery: Limits reset automatically, no manual intervention needed

Temporary Bans

Repeatedly exceeding rate limits may result in temporary IP bans:

First violation: Warning, no ban
Multiple violations: 5-minute ban
Persistent violations: 1-hour ban
Severe abuse: 24-hour ban or permanent restriction

To avoid bans, implement proper rate limit handling in your application.

Best Practices

✓Monitor Rate Limit Headers - Check X-RateLimit-Remaining before making requests
✓Implement Exponential Backoff - When you receive a 429 response, wait with exponential backoff before retrying
✓Cache Responses - Cache frequently accessed data (like exchange rates) to reduce API calls
✓Batch Operations - When possible, batch multiple operations to reduce request count
✓Use Webhooks - Subscribe to webhooks instead of polling for order status updates

Exponential Backoff Example

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') || '1');
      const backoffTime = Math.min(
        retryAfter * 1000 * Math.pow(2, attempt),
        60000 // Max 60 seconds
      );
      
      console.log(`Rate limited. Waiting ${backoffTime}ms before retry...`);
      await new Promise(resolve => setTimeout(resolve, backoffTime));
      continue;
    }
    
    if (!response.ok) {
      throw new Error(`Request failed: ${response.status}`);
    }
    
    return response.json();
  }
  
  throw new Error('Max retries exceeded');
}