Rate limiting

Rate limiting applies to the Paddle API. Send up to 240 requests per minute before getting a 429 error.

Rate limiting helps protect the Paddle platform and make sure it works smoothly for everyone. It works by putting a cap on the amount of requests that an IP address can make in a certain timeframe.

If you send too many requests, you'll get an error with a 429 response code.

429 - Too Many Requests

1
2
3
4
5
6
7
8
1{
2  "error":{
3    "type":"api_error",
4    "code":"too_many_requests",
5    "detail":"You have exceeded the allowed rate limit, please retry your request after the number of seconds in the Retry-After header.",
6    "documentation_url":"https://developer.paddle.com/errors/too_many_requests"
7  }
8}

Our rate limits are designed to protect the Paddle platform from abuse and maintain system stability. The limits are high enough to handle sales and promotions, along with other spikes in traffic. Contact the Paddle Seller Support team if you think you may exceed the limits.

Rate limits

Rate limiting may change. We'll communicate any changes in plenty of time on our developer changelog.

Platform rate limits

All operations in the Paddle API are rate limited, except the preview transaction and preview prices operations.

An IP address can make up to 240 requests per minute.
If exceeded, subsequent requests return a too_many_requests error (429).
When you get this error, that IP address can't make another request for 60 seconds.

Scheduled

Subscription rate limits

Subscription rate limits are scheduled to go into effect on December 9th, 2024. For more information, see: Limits when making subscription changes that result in an immediate charge

There are additional limits in place for requests that update a subscription and result in an immediate charge. For example, upgrading a subscription using prorated_immediately or full_immediately as the proration_billing_mode with no credit balance available.

An account can make up to 20 chargeable updates to a subscription per hour, with a maximum of 100 per 24-hour period.
If exceeded, subsequent requests return a subscription_immediate_charge_hour_limit_exceeded or subscription_immediate_charge_24_hour_limit_exceeded error (429).
When you get these errors, you can't make another immediate charge for that subscription until the next hour or day.
These limits apply on a per-subscription basis to help maintain a good customer experience. There's no overall cap on the number of immediate charges across all subscriptions.

Handle rate limiting

When you get a too_many_requests error, it includes a Retry-After response header to let you know how long to wait before retrying your request. You should avoid making requests during this time.

To handle platform rate limiting, we recommend watching for too_many_requests errors and building a retry mechanism that runs when the limit has expired.

Avoid rate limiting

To reduce your risk of being rate limited and make your integration as performant as possible, it's good practice to design your integration to use as few requests as possible.

You can use the include parameter to get related entities when making a request, rather than making multiple requests. For example, you can include all related prices when getting a product:

GEThttps://api.paddle.com/products/{product_id}?include=prices

product_idstring

Paddle ID of the product entity to work with.

includearray[string]

Include related entities in the response. Use a comma-separated list to specify multiple entities.

Rather than sending requests in a loop, we recommend:

Subscribing to webhooks to let you know when something's changed.
Caching data that you'll use again for a short period — especially if you're building client-side applications.

If you're regularly being rate limited, contact the Paddle seller support team who can help.

Errors

Related entities