Piano reserves the right to block API calls to Subscription Management + Billing or Identity Management publisher endpoints if the system recognizes them as abuse. The limiter considers the amount of actually consumed resources, so it filters both too frequent and too heavy requests. The default limits per method can be estimated as:
-
1-1000 calls per second, but not more than 30,000 calls in 5 minutes for Identity Management
-
1-1000 calls per second, but not more than 15,000 calls in 5 minutes for specific endpoint groups of Piano Management + Billing APIs (e.g. user-related
/publisher/user/*, conversion-related/publisher/conversion/*, etc.) -
1-5000 calls per second, but not more than 60,000 calls in 5 minutes for Piano Management + Billing APIs not assigned to any specific group (e.g.
/publisher/offer/*, any other endpoints).
In considering the above estimates ("1-1000", "1-5000"), please take note of the cost-based nature of our rate limiting, which counts the total call load rather than the number of calls. Thus, if your request is really heavy (taking the server, say, 39 seconds to process), we may have to return "HTTP status: 429 (too many requests)" even at 0.5 requests per second.
If you keep getting Error 429 from our endpoints, please review your integration: decrease the rate of calls or use caching on your application.
We can restrict a specific set of APIs for a duration of up to 5 minutes under two conditions: firstly, if a single request surpasses a processing time of 400 seconds, and secondly, in cases where a rapid succession of requests collectively exceeds a total processing time of 400 seconds. There are no rate limits for more than 5 minutes in the system; this is a hard maximum.
In general, API calls have a timeout of 15 seconds that can't be increased. Any API call that takes longer will return an error code 500 response.
The limitation does occur on an AID basis, but also takes into consideration the type of endpoint that was used.
For example, if a subscription-related endpoint (with a path containing /subscription/*) is abused and thus blocked, API calls to endpoints related to user search or conversion functionality (e.g., with a path containing /user/search or /conversion/*) will still be possible for the same AID/API token.
Rate limits for the different AIDs are independent of each other, even if the requests are being sent from the same IP address. For the rate limiting, we take into account the sum of API calls per AID, even if they are sourced from multiple different servers or IP addresses.
Rate limit response headers
Piano's API uses a token-based rate limiting system to ensure fair usage and consistent performance across all clients. Each API request consumes one or more tokens from a shared cluster-wide budget, with the cost varying based on the complexity and server-side processing time of the request. The following response headers are included with every API response to help you monitor your current rate limit status, understand per-request costs, and implement efficient request throttling in your integration.
-
ratelimit-remaining Estimated number of requests you can still make in the current time window, across the entire API cluster.
Calculated as:
floor(cluster_tokens_remaining / cost_of_this_request)Because this uses the current request's cost as a baseline, it assumes future requests have similar cost. Requests that take longer consume more tokens (see
x-ratelimit-cost-tokens), so the actual remaining count may be lower if you make slower calls. -
x-ratelimit-remaining-tokens Raw token count remaining in the current rate limit window, cluster-wide. Useful if you want to implement your own request-cost estimate rather than relying on
ratelimit-remaining.Example:
x-ratelimit-remaining-tokens: 710Relationship to
ratelimit-remaining:ratelimit-remaining = floor(x-ratelimit-remaining-tokens / x-ratelimit-cost-tokens) -
x-ratelimit-cost-tokens How many tokens this specific request consumed. Minimum is 1. Requests that take longer to process consume additional tokens proportional to their server-side duration. 1 second of server processing is 40 tokens.
Example:
x-ratelimit-cost-tokens: 3A fast, lightweight call typically costs 1–2 tokens. Heavy calls (large result sets, complex queries) may cost more. Use this header to understand why your
ratelimit-remainingdrops faster on some endpoints.
Token Window
The rate limit operates over a 5-minute rolling window. Tokens refill continuously throughout the window, there is no hard reset at a fixed clock boundary.
Recommendations:
To ensure optimal performance and prevent any unexpected failures, we recommend implementing request throttling once ratelimit-remaining reaches 10 (pause for a second, for example, to allow the limit to refill).
Frontend requests
Frontend requests to /user/ endpoints (sent via tp.api.callApi) and other anonymous endpoints are not subject to server-side rate limits. However, a client-side rate limit is enforced by the Piano JavaScript client as a protective measure.
Specifically, the frontend enforces a limit of 30 requests per 60-second sliding window per page session. This is implemented using a sliding window algorithm, meaning new requests become available as older request timestamps age past 60 seconds; not exactly one minute after the limit is reached.
For example, if 30 requests are made within 30 seconds, new requests will begin to succeed approximately 30 seconds later, as the earliest requests fall outside the 60-second window.
If the limit is exceeded, additional API calls made via tp.api.callApi are silently dropped until the request rate falls back within the allowed threshold. Because these requests are dropped rather than queued or rejected with a server error, this behavior may impact implementations that expect a response for every call. The restriction can also be reset by reloading the page.
This limitation is implemented entirely on the client side and does not involve backend throttling. It is designed to prevent unusually high volumes of API requests that may result from misconfiguration or potentially malicious behavior.
Exception: The /anon/error/log endpoint is exempt from client-side rate limiting to ensure that error logging remains functional even if other requests exceed the threshold.
Separately, backend-to-backend API calls to /publisher/ endpoints are subject to their own server-side rate limits, as described above.
In special cases, please contact our Piano support team at support@piano.io for further assistance.