Rate Limiting

What’s rate limiting?

Ocelot Own Implementation

Ocelot provides rate limiting for upstream requests to prevent downstream services from becoming overwhelmed. [1]

Rate Limit by Client’s Header

To implement rate limiting for a Route, you need to incorporate the following JSON configuration:

"RateLimitOptions": {
  "ClientWhitelist": [], // array of strings
  "EnableRateLimiting": true,
  "Period": "1s", // seconds, minutes, hours, days
  "PeriodTimespan": 1, // only seconds
  "Limit": 1
}

  • ClientWhitelist - An array containing the whitelisted clients. Clients listed here will be exempt from rate limiting. For more information on the ClientIdHeader option, refer to the Global Configuration section.

  • EnableRateLimiting - This setting enables rate limiting on endpoints.

  • Period - This parameter defines the duration for which the limit is applicable, such as 1s (seconds), 5m (minutes), 1h (hours), and 1d (days). If you reach the exact Limit of requests, the excess occurs immediately, and the PeriodTimespan begins. You must wait for the PeriodTimespan duration to pass before making another request. Should you exceed the number of requests within the period more than the Limit permits, the QuotaExceededMessage will appear in the response, accompanied by the HttpStatusCode.

  • PeriodTimespan - This parameter indicates the time in seconds after which a retry is permissible. During this interval, the QuotaExceededMessage will appear in the response, accompanied by an HttpStatusCode. Clients are advised to consult the Retry-After header to determine the timing of subsequent requests.

  • Limit - This parameter defines the upper limit of requests a client is allowed to make within a specified Period.

Global Configuration

You can set the following in the GlobalConfiguration section of ocelot.json:

"GlobalConfiguration": {
  "BaseUrl": "https://api.mybusiness.com",
  "RateLimitOptions": {
    "DisableRateLimitHeaders": false,
    "QuotaExceededMessage": "Customize Tips!",
    "HttpStatusCode": 418, // I'm a teapot
    "ClientIdHeader": "MyRateLimiting"
  }
}

  • DisableRateLimitHeaders - Determines if the X-Rate-Limit and Retry-After headers are disabled.

  • QuotaExceededMessage - Defines the message displayed when the quota is exceeded. It is optional and the default message is informative.

  • HttpStatusCode - Indicates the HTTP status code returned during rate limiting. The default value is 429 (Too Many Requests).

  • ClientIdHeader - Specifies the header used to identify clients, with ClientId as the default.

Future and ASP.NET Core Implementation

The Ocelot team is contemplating a redesign of the Rate Limiting feature following the Announcing Rate Limiting for .NET by Brennan Conroy on July 13th, 2022. Currently, no decision has been made, and the previous version of the feature remains part of the 20.0 release for .NET 7. [2]

Discover the new features being introduced in the ASP.NET Core 7.0 release:

While retaining the old implementation as an Ocelot built-in feature makes sense, we plan to transition to the new Rate Limiter from the Microsoft.AspNetCore.RateLimiting namespace.

Please share your thoughts with us in the Discussions space of the repository. octocat