Rate Limiting

In order to ensure responsible use of the Eclipse API’s and protect all tenants from denial of service attacks as well as accidental issues caused by bugs in Apps and backends, the Eclipse API gateway rate limits requests based on configurable rules. New tenants have a reasonable default set up and as tenants grow with legitimate traffic, rate limits are increased while ensuring sufficient capacity to cover the traffic of all tenants.

The rate limits are monitored based on windows (a time frame in which the number of API calls are counted and determined to be within or outside the limit). The limits themselves are applied based on 3 possible pieces of information from a request:

1.The IP address making the request
2.The tenantId in the JWT of the request
3.The userId in the JWT of the request

If a request has a JWT, then (2) and (3) are considered. Otherwise, (1) is considered as the call is anonymous and all that can be determined is what IP did the request.

For (2) and (3), the first rate limit to be hit results in an error being returned back to the caller (code RLT001). I.e. if a call results in the limit per user being hit, but the limit per tenant is not hit, a rate limit error will be returned. If the limit for the tenant is hit, then a rate limit error will be returned for all calls with a JWT for that tenant, irrespective of the user or source IP.

For (1), if the rate limit per IP is hit then all calls from that IP without a JWT will result in a rate limit error.
Rate limits also include concurrency limits - i.e. how many calls can currently be processed by Eclipse at any point in time. Much like rate limits, they also apply per IP, user and tenant depending on whether a JWT is passed in the request or not. Unlike rate limits, concurrency limits do not relate to a window of time, but rather any instant in time.

To understand where ones limits are at for any request, the response headers will include information about the rate limit that is closest to being hit. E.g.:

• RateLimit-ConcurrencyRemaining: 10
• RateLimit-Limit: 1200;window=600;policy="per.user";concurrency=10
• RateLimit-Remaining: 1165
• RateLimit-Reset: 507

In the above example, the headers say that the limit is 1200 calls in a 600 second window. The policy closest to being hit is the per user policy. The max concurrency allowed is 10 and now that this call is complete, 10 are still available (i.e. no other calls are in progress). At this stage, 1165 calls are allowed in the rest of the window which lasts for another 507 seconds (i.e. the current window is 93 seconds old).

The next example is the result of a call which did not have a JWT. One can see that the policy per IP is being considered and in this case it was the first call in the window and 1199 calls remain for the next 600 seconds.

• RateLimit-ConcurrencyRemaining: 10
• RateLimit-Limit: 1200;window=600;policy="per.ip";concurrency=10
• RateLimit-Remaining: 1199
• RateLimit-Reset: 600

When a rate limit is hit, the caller would need to wait for the next window to open and then the calculations start again.

By default, the rate limits for a tenant are as follows:
Tenant level - 1200 calls in a 600 second window (i.e. averaging 2 calls/second for 10 minutes), 20 concurrent
User level - 1000 calls in a 600 second window, 20 concurrent
IP level - 40 calls in a 10 second window, 10 concurrent

If one is concerned that the default rate limits are too low, please work with your solution architect to agree on an adjusted set of limits that make sense for ones use case.

NB: Rate limits will not be adjusted in the case of poor use of the Eclipse API - e.g. running batches unnecessarily or getting data for example across all wallets one by one when a report would be a better use case/solution.

📘

Note

Rate limits are controlled by global property rate.limit.config.