Rate limits

API rate limits are controls that protect Airwallex systems by limiting the number of requests allowed over a specified period. They ensure fair access to Airwallex APIs for all users and maintain predictable, stable service performance.

Limit types

Airwallex enforces two types of limits.

Rate limit

Rate limits control how many requests can be made over a rolling time period. This prevents excessive bursts of traffic that could degrade service performance.

For example, a rate limit of 100 requests per second means you can make up to 100 API calls within any one-second window. If you exceed this threshold, additional requests are rejected with an HTTP 429 status code until the rate drops below the limit.

Concurrency limit

A concurrency limit controls how many active requests (pending for response) are allowed at any given time. This prevents a single account from monopolizing server resources with long-running or slow requests.

For example, a concurrency limit of 50 means you can have up to 50 simultaneous API requests awaiting responses. Once this limit is reached, additional requests are rejected until existing requests complete.

Limit levels

Limits are applied at multiple levels to provide granular control and protection.

Global level

The global level represents the aggregate limit across all endpoints for a given account or organization. This is the total number of requests or concurrent connections allowed regardless of which specific endpoints are being called.

Endpoint level

The endpoint level applies to an individual API operation across all instances of that resource type.

For example:

• POST /api/v1/pa/payment_intents/{id}/confirm: Confirm a Payment Intent
• GET /api/v1/deposits: Get list of Deposits
• POST /api/v1/transfers/create: Create a new Transfer

Each of these endpoints has its own limit that counts separately from other endpoints, though they all contribute to the global limit.

Resource level

The resource level applies to operations on a single, specific resource.

For example:

• POST /api/v1/pa/payment_intents/int_hkpdp4tjth9mt2both9/confirm: Confirm a specific Payment Intent
• GET /api/v1/transfers/tr_wn7uEO-YPxmPr2w5JNKb1A: Retrieve a specific Transfer

Certain API resources have specific rate and concurrency limits to ensure performance or data consistency. Refer to the API Reference API for details about specific resources.

Production and sandbox limits

Airwallex applies different limits based on the environment.

If you require higher limits for your production use case or a temporary uplift for an upcoming flash sale, contact Airwallex support to discuss your needs.

Error response

When a request exceeds a limit listed above, Airwallex returns an error response with an HTTP 429 (Too Many Requests) status code.

JSON
1{
2  "code": "too_many_requests",
3  "message": "Rate Limit Exceeded.",
4  "trace_id": "65550cb69fbe78b760be650a64d00269",
5  "details": {}
6}

Handle limiting

To handle limiting effectively, implement a retry mechanism that responds to 429 status codes. Use exponential backoff to progressively increase wait times between retry attempts, reducing request volume when limits are reached. Add random jitter to your backoff intervals to prevent multiple clients from synchronizing their retries and overwhelming the API.

For example, after receiving a 429 response:

1. Wait 1 second before the first retry.
2. Wait 2 seconds before the second retry.
3. Wait 4 seconds before the third retry.
4. Continue doubling the wait time up to a maximum threshold (for example, 16 seconds).

For scheduled batch tasks or high-volume operations, implement a client-side throttling algorithm to stay within your account or endpoint limits.

Load testing

Airwallex discourages conducting load tests in the sandbox environment. The sandbox enforces lower rate and concurrency limits, which means your load tests are likely to encounter limits that wouldn't occur in production. Additionally, the sandbox isn't a perfect representation of production because it uses various mock mechanisms, resulting in different latency profiles that don't reflect real-world performance.

For more realistic load testing, build your integration with the ability to mock Airwallex APIs. Your mocks should simulate realistic latency based on measurements from actual production API calls. This approach allows you to test your system's behavior under load without hitting sandbox limits or generating misleading performance data.