Rate limiting

API rate limits help keep Mollie’s APIs reliable, fair, and predictable for all customers. This page explains what API rate limits are, how they work at Mollie, and how to prepare your integration with our API.

What are API rate limits?

API rate limits control how many requests can be made within a certain time period.
They help to:

• Keep the platform reliable for all customers
• Prevent accidental overloads
• Protect against misuse
• Ensure fair access to shared capacity

Rate limits are designed to enable healthy business growth and are here to make sure one integration's error or traffic spike does not affect any other business processes.

How rate limits work at Mollie

Rate limits may apply across all public APIs but not all actions have the same limit.
Different API endpoints have different expected usage patterns and different system impact, so limits are not one flat rule across all APIs (e.g., GET queries vs POST, test mode vs live mode etc).

The limits are dynamic and are calculated based on observed traffic patterns to ensure specific business's success.

Rate limits are measured in requests per second. Burst capacity allows you to temporarily exceed your rate limit during short traffic spikes. This additional capacity is designed to accommodate legitimate bursts without treating them as misuse.

Hitting a rate limit

If your integration sends more requests than allowed in a given period, the API may return the following error: HTTP 429 Too Many Requests.

If that happens, you should:

• Wait before re-running the queries
• Use retry and backoff logic
• Avoid sending repeated bursts immediately
• Use efficient API patterns where possible
• Check the Retry-After and RateLimit headers to pace your requests.
  • Retry-After — integer seconds until your next request slot opens. Only present on 429 responses.
  • t in RateLimit — seconds remaining in the current rate window, always 0 or 1. Use this to know when your rate slots replenish.
  • mollie-burst in RateLimit — remaining burst headroom. If this is 0, your burst budget is exhausted and Retry-After carries the full back-off duration.
• Contact Mollie if you need increased capacity*
  (*requests and use cases are reviewed individually)

Understanding rate limit headers

Every API response includes rate limit headers so you can monitor your quota in real time and pace your API requests before hitting a limit.

The Retry-After header is expressed as an integer and is written as a number of seconds. For example, a 30-second back-off is written as 30.

Here is an example response:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
RateLimit-Policy: "get-v2-payments";q=20;w=1;mollie-burst=60
RateLimit: "get-v2-payments";r=0;t=1;mollie-burst=0
Retry-After: 1

{
  "status": 429,
  "title": "Too Many Requests",
  "detail": "You have exceeded the rate limit. Please slow down your requests.",
  "_links": {
    "documentation": {
      "href": "https://docs.mollie.com/overview/handling-errors",
      "type": "text/html"
    }
  }
}

This tells you the following information about your limits:

1. You have 20 requests in your get-v2-payments bucket & the maximum cooldown after a full spike is 3 seconds.
2. Currently, you have 15 requests left and if you stop making requests, the bucket will be fully drained in 2 seconds (and your full capacity of 20 will be restored).

When you are approaching the limit, we recommend slowing down on your requests rather than burning through the bandwidth you have left.

Read and write limits

All API keys and OAuth apps acting on behalf of the same merchant share the same bucket. The policy name in RateLimit-Policy and RateLimit tells you which bucket applies to your request.

A merchant seeing q=200 on a GET /v2/payments request and a q=50 on a POST /v2/payments request is seeing two separate buckets, not a change in their overall quota as the read and write limits are tracked separately.

Rate limits in test mode

Rate limiting also applies to our test mode but it may have lower limits than live environments. This is because test mode is intended for testing the integration, not load or capacity testing.

If you need help preparing for a high-volume live event or peaking traffic, contact Mollie rather than trying to simulate it in the test mode.

Checking your limit status

You can check rate limits in two ways:

• Response information - all API responses include RateLimit-Policy and RateLimit headers showing your current bucket's state.
• Web App visibility - you can view your current limit status and request additional capacity right in your Mollie account.

To do so, go to the Web App > Developers > Overview and you will see your API usage.

The view is broken down by Read and Write sections, each showing a graph with your hourly usage (click View Logs to go to the detailed view). You can also switch between the tabs Live mode and Test mode that help you to distinguish between two modes.

Insights on the right show you a brief 'health check' of your usage and offers active alerting if there is:



1. Upward API usage
2. Reached API usage limit

You can request a temporary rate limit change by clicking Request an increase - this will prompt a form with basic information our team needs to assess your request.
These requests should be submitted in advance to allow for appropriate planning and review on our side. See Requesting higher limits for elevated traffic below for more information.

Make sure to review your rate limit status regularly to build a reliable integration and ensure all your requests are processed correctly.

Requesting higher limits for elevated traffic

If you are planning a high-demand event or have a business need that does not fit the default limits, you can request additional capacity in advance and we will review your eligibility. This gives us time to:

• Review your expected traffic
• Check if your current limits are sufficient or need to be adjusted
• Support you with a temporary increase if needed

Example: flash sales, ticket launches, seasonal peaks, migration or import activity, other planned periods of unusually high traffic etc.

You can submit your request in two ways:

• In your Web App under Developers > Overview > Request an increase
• Reach out to your Customer Success Manager in Mollie so they can assist you.

The more in advance you reach out, the more efficient we can be in helping your business's use case.