Troubleshooting Rate Limits & Idempotency

When integrating high-volume checkouts or automated reconciliation batch jobs, understanding Amwal's rate limits and idempotency mechanisms is crucial for preventing dropped requests and double charges.

Rate Limit Thresholds

Amwal REST APIs enforce the following rate limits per merchant API key:

When limits are exceeded, the API returns HTTP 429 Too Many Requests along with standard rate limit headers:

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

Preventing 429 Errors: Best Practices

1. Use Webhooks Instead of Polling: Do not poll /payment_links/{payment_link_id}/details in a high-frequency loop to check if an order has been paid. Subscribe to the order.success webhook event instead (payment_link.completed is not a real event — see Webhook Event Types for the actual supported list). Note that webhook delivery alone doesn't replace polling entirely: setting callback_url requires a separately-registered webhook endpoint to actually fire, and delivery is at-least-once — see Webhook Delivery Issues.
2. Implement Exponential Backoff: When receiving a 429 response, parse the Retry-After header and wait before retrying:

async function fetchWithRetry(url, options, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const res = await fetch(url, options);
    if (res.status !== 429) return res;
    
    const retryAfter = parseInt(res.headers.get('Retry-After') || '2', 10);
    const delay = retryAfter * 1000 + Math.random() * 500;
    await new Promise((resolve) => setTimeout(resolve, delay));
  }
  throw new Error('Rate limit exceeded after multiple retries');
}

Preventing Duplicate Charges (Idempotency)

When generating payment links via the Create Payment Link API, always supply a unique order_id in the request body:

{
  "amount": 499.00,
  "order_id": "ORD-2026-981240",
  "singleUse": true
}

• If a network disconnect occurs and your server re-submits the identical order_id, Amwal detects the in-flight order and returns the existing payment link rather than generating a duplicate link.