Rate limiting

Rate limiting is the controlling of requests received and processed in a given time period.

The Mangopay API relies on rate limiting to ensure stable and reliable behavior for all clients, in both the Production and Sandbox environments.

​

Limits per time period

Rate limits apply to all endpoints. The maximum number of calls allowed in a given period is as follows:

If you exceed the rate limits, you receive a 429 HTTP response code with the following response body:

{
  "Message": "Rate limit exceeded. Please contact support for more assistance",
  "Type": "rate_limit",
  "Id": *,
  "Date": *,
  "errors": null
}

​

Response header information

The response header of all API calls provides useful information regarding the rate limit:

• x-ratelimit indicates the number of API calls you have made.
• x-ratelimit-remaining indicates the number of API calls you have left before reaching the limit.
• x-ratelimit-reset indicates how long you have to wait until reset (in timestamp format).

In the header, the returned values represent rate limits for intervals of 15 minutes, 30 minutes, 1 hour, and 24 hours, respectively.

For example:

• X-RateLimit: 63015, 121914, 228534, 7103921.
• X-RateLimit-Remaining: 436985, 878086, 1771466, 40896079.
• X-RateLimit-Reset: 1715241060, 1715241960, 1715243760, 1715326500

The header information can prove particularly useful if you plan on making a lot of API requests in a short period of time (such as batch payouts or transfers for instance). 

The rate limit information can allow you to:

• Automatically stop sending requests once the limit has been reached and then start making requests again at the x-ratelimit-reset time
• Automatically set pauses in between calls to ensure you don’t go over the limit

​

API implementation best practices

An implementation can be optimized to avoid reaching the rate limits.

The following oversights commonly increase the risk of exceeding the rate limit:

• Failed requests being indefinitely retried
• Systematic GET requests without the platform storing or caching the corresponding information
• GET requests made daily while they could be made at a larger interval (weekly, monthly)
• Requests triggered on a fixed interval while they could be triggered after the corresponding POST request has been made instead

​

Leaky bucket algorithm

The API rate limiting relies on what’s known as a leaky bucket algorithm. The bucket collects requests up to a maximum capacity and processes them at a set rate. Once the maximum capacity is reached, additional requests are discarded.

This algorithm makes it possible to store up bursts of requests while processing them at a steady rate. In addition, the bucket allowance slides for each window rather than being reset at a specific interval in the hour.

For example, with a 15-minute bucket, if you reach the limit of 10 calls, you’ll need to wait 15 minutes to release those 10 calls from your allowance (as opposed to waiting until 15 minutes past the hour).