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:

HeaderDescription
x-ratelimit-limitThe maximum number of requests permitted per rate limit window.
x-ratelimit-remainingThe number of requests remaining in the current rate limit window.
x-ratelimit-resetA 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.

ModeLimit
Live600 requests per 60 seconds
Test100 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:

EndpointLimit
Verify Transaction3,000 requests per 60 seconds
Resolve Account Number1,500 requests per 60 seconds
Initialize Transaction1,200 requests per 60 seconds
Charge Authorization1,200 requests per 60 seconds
Create Charge1,200 requests per 60 seconds
Check Pending Charge1,200 requests per 60 seconds
Initiate Transfer900 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:

  1. Read the x-ratelimit-reset value (in seconds) from the response headers.
  2. Pause requests to that endpoint until the window ends.
  3. 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:

  1. Listen for webhooks instead of polling. The most common source of 429 responses is polling immediately after an asynchronous request is made. For example, calling /transaction/verify/:reference in 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.
  2. Cache stable lookups. /bank/resolve always 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.
  3. Batch when reconciling. Use the /transaction list endpoint with a date range during reconciliation instead of calling verify once per reference. By default, a list request returns 50 items.
  4. 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.