API Rate Limits
Fenergo's platform is designed with a number of safeguards in place to prevent bursts of incoming traffic, maximising the performance and stability of the product for all users.
Why does Fenergo use Rate Limits?
Applying API rate limiting serves several purposes:
Preventing Abuse: Prevents a single user or group from overloading the system with a high number of requests, intentionally or unintentionally. This is particularly important for public APIs where a user might send a large number of requests in a short period of time, causing a denial of service.
Ensuring Fair Usage: By limiting the number of requests, rate limiting ensures that all users get a fair share of the system’s resources.
Maintaining System Stability and Resiliency: By preventing the system from being overwhelmed by too many requests, rate limiting helps maintain the system’s stability and performance.
Types of Rate Limiters
Fenergo implements two strategies in regulating traffic: Tenant and Domain API rate limits.
Tenant Limits
Tenant Limits are applied to all incoming authenticated traffic at Fenergo’s gateway, excluding Application Users. When the limit is reached, and tenant requests are throttled they will get the HTTP Status code 429 in response until the window expires (1 second).
We define two usage plans based on the type of Tenant.
| Production | SDLC | |
|---|---|---|
| Rate Limit - number of requests per second | 200 | 50 |
| Burst Limit - number of concurrent requests | 50 | 10 |
Domain API Limits
Domain API Limits apply to a subset of Domains which have their own limits on how many requests can be handled at one time. These limits are based on all traffic, including Application Users so be careful that your integrations do not use the full allotment as this can impact users accessing the application through the UI.
| Category | Command Type | Production (Minute) | Production (Hour) | Production (Day) | SDLC (Minute) | SDLC (Hour) | SDLC (Day) |
|---|---|---|---|---|---|---|---|
| Journey | Command | 100 | 2500 | 15000 | 90 | 1250 | 5000 |
| Entity Data | Command | 200 | 2500 | 15000 | 150 | 2500 | 10000 |
| Product | Command | 200 | 2500 | 15000 | 150 | 2500 | 10000 |
| Data | Deletion | 200 | 2500 | 60000 | 150 | 2500 | 10000 |
| Event | Ingress | See Event Ingress Rate Limiting | - | - | - | - | - |
| Comments | - | 200 / second | - | - | 50 / second | - | - |
| Identity | - | 100 / 5 min / IP | - | - | - | - | - |
As with Tenant Limits, when the Domain API Limit is reached the client will receive a response with HTTP Status 429. In addition, we include two headers in the response: X-Rate-Limit-Remaining and X-Rate-Limit-Reset which can be used as a counter in your integration layer to prevent consuming the entire limit.
In this example we see the Domain API has 9992 requests remaining in the current 24-hour window and the window resets on April 09 10:55:30 UTC time.
HTTP/1.1 200 OK
Content-Type: application/json
X-Rate-Limit-Remaining: 9992
X-Rate-Limit-Reset: 2024-04-09T10:55:30.0705512Z
{
"statusCode": 200,
"message": "Request succeeded."
}
- The 24-hour clock starts as soon as the first API call is made.
- These headers don’t include sub-windows (second, minute, or hour).
Rate Limit Increase Requests
Clients can request certain rate limit increases to enable specific high traffic use cases through their designated Client Partner or Solution Architect.
Alternatively, for certain bulk activities that may be required, Fenergo offers other solutions such as data migration and bulk load, where the same rate limits are not applied.
Please work with your Solution Architect to find the right solution for your integration use case(s).
Designing for Rate Limits
Here are several approaches that can ensure resiliency when building integrations with the Fenergo APIs.
Application
A basic technique for integrations to gracefully handle limiting is to watch for 429 HTTP Status codes and build in a retry mechanism. The retry mechanism should follow an exponential backoff schedule to reduce request volume when necessary. We would also recommend building some randomness into the backoff schedule to avoid a thundering herd effect.
You can only optimize individual requests to a limited degree, so an even more sophisticated approach would be to control traffic centrally in your integration and throttle it back if you detect substantial rate limiting. A common technique for controlling rate is to implement something like a token bucket rate limiting algorithm on the client-side. Ready-made and mature implementations for token bucket are available in almost any programming language.
Caching Authentication Tokens
As mentioned in Domain API Limits, the current limit for requesting authentication tokens from Fenergo’s Identity service is 100 requests per IP address over a 5 minute-period. This includes token requests over MTLS.
An authentication token is valid for 15 minutes and should be reused to avoid hitting the Identity Domain’s API Limit. Caching the authentication token means that client integrations can use and re-use the same token for the full window before requesting a new one.
Fenergo recommends centrally managing the Authentication Token (issue and renewals) alongside the Token Bucket pattern above as the start of a well-architected framework.