Overview #
To avoid Cyclr making calls to external systems faster than they will allow – or perhaps can process – you can define Rate Limits on your Custom Connectors.
A system might publish their API limits in their documentation, e.g. 1,000 Requests/Second, or up to 1,000,000 Requests/24 hours.
You can create Rate Limits on a Connector Release at the overall Connector-level as well as at the Method-level. This allows general limits used by an API to be set globally on a Connector, and then gives you the ability to override them for a particular Method.
Some external systems provide different limits on different parts of their API so being able to set Rate Limits at different levels of a Connector allows Cyclr to respect and work within those limits.
When running Templates and Cycles, Cyclr records how many API calls it’s made and will pause if making further calls would exceed any related Rate Limits on the Connector. This results in API calls being queued until the Rate Limits indicate it’s okay to continue making calls.
This is all automatic within Cyclr and doesn’t require any intervention by the user.
Note: November 2024: Rate Limits have been improved!
Rate Limits created on Custom Connectors or Library Connectors before mid-November 2024 will continue to function as before. Rate Limits created after then will function as described in this article.
Pre-November 2024 behaviour is for Cyclr to gather Connector-level and Method-level Rate Limits and apply only the most restrictive Rate Limit.
Specifiying a Rate Limit #
When working on a Custom Connector, you can specify Rate Limits as appropriate to the system your Connector will be calling. These are usually explained within the documentation of an API.
Go to your Cyclr Console, then Connectors > Custom Connectors and edit a Draft Release of your Connector.
- If you’re adding a Rate Limit that applies to all of your Connector’s Methods, go to the Connector-level “Rate Limits” tab.
- If you’re adding a Rate Limit that only applies to a specific Connector Method, go to the “Methods” tab, locate that Method and edit it, then go to its “Rate Limits” tab.
Cyclr’s Rate Limits can be specified in two ways – which you use depends on which better fits the limits of the API you’re working with:
- Maximum Requests Per Time Frame
- Time Between Requests
Maximum Requests Per Time Frame #
This allows you to specify the number of calls Cyclr can make within a set period of time, e.g.:
- Up to 1,000 Requests every 1 Second
- Up to 10,000 Requests every 60 Minutes
The smallest Time Unit available here is Seconds.
Time Between Requests #
This allows you to have Cyclr wait between each call, e.g.:
- 1 Request every 500 Milliseconds
- 1 Request every 5 Seconds
The smallest Time Unit available here is Milliseconds.
When Multiple Rate Limits Apply #
If Rate Limits are defined at both the Connector-level and Method-level, Cyclr will retrieve all the related limits when executing a Connector Method and use the most restrictive limit to determine whether it can make a call now or must wait.
When the Rate Limits allow the call to go ahead, Cyclr will record the activity which will go towards those related limits for future Rate Limit calculations.
Some APIs provide a daily limit and also a “burst limit”, allowing systems like Cyclr to make lots of calls over a whole day, but restricting them from all being used within a short space of time.
An example might be 100,000 calls each day, but no more than 100 calls within 1 minute.
That could be implemented as 2 separate Connector-level Rate Limits:
- Connector-level Rate Limit for “Maximum Requests Per Time Frame” of
100,000 Requests/24 hours. - Connector-level Rate Limit for “Maximum Requests Per Time Frame” of
100 Requests/1 minute.
Overriding Connector-level Rate Limits #
Method-level Rate Limits have an additional option called Override Connector Rate Limits?
Turning this on will ignore any Connector-level Rate Limits and only use those defined at the Method-level.
If no Rate Limits have been set at the Method-level, no rate limiting will occur, resulting in Cyclr making calls to that Method as quickly as it can.
Calls to Methods with that option enabled won’t be counted towards any other Rate Limits of that Connector so there’s no impact on other Methods.
Custom “Retry After” Header #
Not all APIs provide this, but when some are receiving requests too quickly for them to process, they may return “429 Too Many Requests” errors. They usually include a Retry-After HTTP Header which contains a time value indicating when it’ll start accepting requests again which Cyclr will automatically use.
If an API uses a different HTTP Header for this, you can provide its name in the Custom Retry After Header field.
Note: The value is case-sensitive so must exactly match the name of the HTTP Header that API uses.
