Rate limiting

The Mambu Payments API is rate limited. API requests above the rate limit will return an HTTP 429 - Too Many Requests response code. These API requests are not processed by Mambu Payments and can be retried with the same idempotency key with no risk.

Exponential backoff and jitter

To retry API requests that were rejected due to rate limiting, we recommend using an exponential backoff with jitter:

Exponential backoff: wait 1 second, then 2 seconds, then 4 seconds, etc.
Jitter: add a random millisecond value to your wait time (e.g., wait 4.23 seconds instead of exactly 4 seconds) to avoid the thundering herd problem

Best practices to prevent rate limiting

To prevent rate limiting, we recommend:

Implementing client-side throttling with queue-based processing or token bucket algorithm
Caching GET responses
Using bulk actions to create payment orders, internal accounts, and VOP requests
Using webhooks to receive events instead of polling the API