Rate Limits
API rate limiting, request windows, rate limit headers, and best practices to stay within limits.
Copy linkOverview
Rate limiting is one of the mechanisms we use in our infrastructure to ensure the stability of our API. It provides guardrails to avoid an outburst of API requests. This means there is a limited number of requests you can make per time window for each endpoint. Going beyond this limit returns a 429 error, indicating that you need to reduce your request rate.
Copy linkRate limit headers
When you receive a 429, parse the response headers to know how to proceed:
| Header | Description |
|---|---|
| x-ratelimit-limit | The maximum number of requests permitted per rate limit window. |
| x-ratelimit-remaining | The number of requests remaining in the current rate limit window. |
| x-ratelimit-reset | A time in seconds indicating when the current limit window ends. It tells you when you can retry the request. |
Copy linkStandard limits
Most endpoints share a default limit. Limits apply per integration with separate quota for live and test mode.
| Mode | Limit |
|---|---|
| Live | 600 requests per 60 seconds |
| Test | 100 requests per 60 seconds |
Info: Test mode is for development and integration testing, not load testing.
Copy linkExtended limits
Certain foundational endpoints have higher dedicated limits in order to ensure critical business operations run smoothly. They include:
| Endpoint | Limit |
|---|---|
| Verify Transaction | 3,000 requests per 60 seconds |
| Resolve Account Number | 1,500 requests per 60 seconds |
| Initialize Transaction | 1,200 requests per 60 seconds |
| Charge Authorization | 1,200 requests per 60 seconds |
| Create Charge | 1,200 requests per 60 seconds |
| Check Pending Charge | 1,200 requests per 60 seconds |
| Initiate Transfer | 900 requests per 60 seconds |
Warning: Extended limits only apply to live mode. Test mode uses the standard limit for all endpoints.
Copy linkHandling a 429
When an endpoint returns a 429, your integration should:
- Read the
x-ratelimit-resetvalue (in seconds) from the response headers. - Pause requests to that endpoint until the window ends.
- If you see sustained
429s across multiple endpoints, pause and investigate. An unchecked loop is usually the cause.
Info: Limits apply per endpoint, not across your integration. When an endpoint is rate limited, other endpoints will keep returning responses until you hit their limit.
Copy linkStaying within limits
In practice, most rate-limit issues come from a few avoidable patterns. To stay well within the limits:
- Listen for webhooks instead of polling. The most common source of
429responses is polling immediately after an asynchronous request is made. For example, calling/transaction/verify/:referencein a loop while awaiting the final transaction status. We send webhook events for asynchronous requests. If you must verify on demand, make calls once per moment. - Cache stable lookups.
/bank/resolvealways returns the same name for the same account number and bank code unless the customer has made a change to their details from their bank. Caching such details also improves your app's performance. - Batch when reconciling. Use the
/transactionlist endpoint with a date range during reconciliation instead of calling verify once per reference. By default, a list request returns 50 items. - Use bulk endpoints for high volume. If you're initiating many transfers or charges, use Bulk Transfer and Initiate Bulk Charge instead of calling the single-item endpoints in a loop. Each bulk request counts once toward your rate limit while processing many items in a batch.
Copy linkCustom limits
Certain businesses have high throughput with unpredictable patterns. If you require higher limits, reach out to [email protected] with:
- The endpoint(s) requiring higher limits
- Your expected sustained and peak request rates
- A brief description of what your integration does
We'll work with you to provision the right limit.