Rate Limiting

BIEASES Payment API implements rate limiting to ensure fair usage, maintain service quality, and protect against abuse. Understanding these limits is crucial for building robust integrations.

Rate Limit Overview

Standard Limits

Environment	Requests per Minute	Requests per Hour	Burst Limit
Sandbox	300	5,000	50
Production	300	5,000	50

Per-Operation Limits

Operation	Requests per Minute	Special Notes
Create Payment	60	Critical operation with stricter limits
Query Payment	120	Higher limit for status checking
Cancel Payment	30	Lower limit to prevent abuse
Refund Payment	20	Strict limit for financial operations
Webhook Verification	No limit	Real-time processing required

Rate Limit Exceeded Response

When rate limits are exceeded, the API returns:

HTTP/1.1 429 Too Many Requests

{
  "code": "42901",
  "msg": "Rate limit exceeded. Try again in 60 seconds.",
  "data": null
}

Implementation Strategies

1. Request Throttling

public class RateLimitHandler {
    private final int maxRequestsPerMinute = 250; // Leave buffer
    private final Queue<Long> requestTimes = new LinkedList<>();
    
    public boolean canMakeRequest() {
        long now = System.currentTimeMillis();
        
        // Remove requests older than 1 minute
        while (!requestTimes.isEmpty() && 
               now - requestTimes.peek() > 60000) {
            requestTimes.poll();
        }
        
        if (requestTimes.size() < maxRequestsPerMinute) {
            requestTimes.offer(now);
            return true;
        }
        
        return false;
    }
}

2. Exponential Backoff

public class ExponentialBackoff {
    private static final int MAX_RETRIES = 5;
    private static final long BASE_DELAY_MS = 1000;
    
    public ApiResponse callWithBackoff(ApiRequest request) 
            throws InterruptedException {
        for (int attempt = 0; attempt <= MAX_RETRIES; attempt++) {
            try {
                return apiClient.call(request);
            } catch (RateLimitException e) {
                if (attempt == MAX_RETRIES) {
                    throw e;
                }
                
                long delay = BASE_DELAY_MS * (long) Math.pow(2, attempt);
                Thread.sleep(Math.min(delay, 60000)); // Max 1 minute
            }
        }
        throw new RuntimeException("Max retries exceeded");
    }
}

Best Practices

1. Proactive Rate Management

// Check rate limits before making requests
public boolean shouldMakeRequest() {
    int remaining = Integer.parseInt(
        lastResponse.getHeader("X-RateLimit-Remaining")
    );
    
    // Reserve 10% buffer for critical operations
    return remaining > (rateLimit * 0.1);
}

2. Request Prioritization

public enum RequestPriority {
    CRITICAL(1),    // Payment creation, refunds
    HIGH(2),        // Payment queries for customer
    NORMAL(3),      // Background status checks
    LOW(4);         // Analytics, reporting
    
    private final int level;
}

3. Intelligent Retry Logic

public class IntelligentRetry {
    
    public boolean shouldRetry(ApiException e) {
        // Retry rate limits and server errors
        if (e.getStatusCode() == 429 || 
            e.getStatusCode() >= 500) {
            return true;
        }
        
        // Don't retry authentication or validation errors
        if (e.getStatusCode() == 401 || 
            e.getStatusCode() == 400) {
            return false;
        }
        
        return false;
    }
}

Rate Limit Increases

Eligibility Criteria

• Production Environment - Must be using production API
• Good Standing - No recent abuse or violations
• Business Justification - Clear business need for higher limits
• Technical Implementation - Proper rate limiting and error handling

Request Process

1. Document Requirements - Provide traffic projections and use cases
2. Technical Review - Demonstrate proper rate limit handling
3. Business Review - Justify business need for increased limits
4. Implementation - Limits increased after approval

Contact Information

For rate limit increases, contact:

• Email: support@bieases.com
• Subject: Rate Limit Increase Request - [Merchant ID]
• Include: Current usage, projected needs, business justification

---

Need higher limits? Contact our Support team to discuss your requirements and eligibility for increased rate limits.