rate-limit.md

description
This page provides the technical details of the Rate Limit policy

Rate Limit

Overview

There are three rate-limit policies:

• Quota: Configures the number of requests allowed over a period of time (hours, days, weeks, months)
• Rate Limit: Configures the number of requests allowed over a limited period of time (seconds, minutes)
• Spike Arrest: Throttles the number of requests processed and sends them to the backend to avoid a spike

Functional and implementation information for the rate-limit policies are organized into the following sections:

• Examples
• Configuration
• Compatibility Matrix
• Errors
• Changelogs

Examples

{% hint style="warning" %} This policy can be applied to v2 APIs and v4 HTTP proxy APIs. It cannot be applied to v4 message APIs or v4 TCP proxy APIs. {% endhint %}

{% tabs %} {% tab title="HTTP proxy API example" %} Quota

Sample policy configuration:

"quota": {
    "limit": "1000",
    "periodTime": 1,
    "periodTimeUnit": "MONTHS"
  }

Rate Limit

Sample policy configuration:

"rate": {
    "limit": "10",
    "periodTime": 10,
    "periodTimeUnit": "MINUTES"
  }

Spike Arrest

Sample policy configuration:

"spike": {
    "limit": "10",
    "periodTime": 10,
    "periodTimeUnit": "MINUTES"
  }

{% endtab %} {% endtabs %}

Configuration

Phases

The phases checked below are supported by the rate-limit policy:

v2 Phases	Compatible?	v4 Phases	Compatible?
onRequest	true	onRequest	true
onResponse	false	onResponse	false
onRequestContent	false	onMessageRequest	false
onResponseContent	false	onMessageResponse	false

Options

You can configure the rate-limit policies with the following options:

Quota

The Quota policy configures the number of requests allowed over a large period of time (from hours to months). This policy does not prevent request spikes.

Property	Required	Description	Type	Default
key	false	Key to identify a consumer to apply the quota against. Leave it empty to apply the default behavior (plan/subscription pair). Supports Expression Language.	String	null
limit	false	Static limit on the number of requests that can be sent (this limit is used if the value > 0).	integer	0
dynamicLimit	false	Dynamic limit on the number of requests that can be sent (this limit is used if static limit = 0). The dynamic value is based on Expression Language expressions.	string	null
periodTime	true	Time duration	Integer	1
periodTimeUnit	true	Time unit (HOURS, DAYS, WEEKS, MONTHS)	String	MONTHS

Rate Limit

The Rate Limit policy configures the number of requests allowed over a limited period of time (from seconds to minutes). This policy does not prevent request spikes.

Property	Required	Description	Type	Default
key	false	Key to identify a consumer to apply rate-limiting against. Leave it empty to use the default behavior (plan/subscription pair). Supports Expression Language.	String	null
limit	false	Static limit on the number of requests that can be sent (this limit is used if the value > 0).	integer	0
dynamicLimit	false	Dynamic limit on the number of requests that can be sent (this limit is used if static limit = 0). The dynamic value is based on Expression Language expressions.	string	null
periodTime	true	Time duration	Integer	1
periodTimeUnit	true	Time unit ("SECONDS", "MINUTES" )	String	SECONDS

Spike Arrest

The Spike Arrest policy configures the number of requests allow over a limited period of time (from seconds to minutes). This policy prevents request spikes by throttling incoming requests. For example, a Spike Arrest policy configured to 2000 requests/second will limit the execution of simultaneous requests to 200 requests per 100ms.

By default, the Spike Arrest policy is applied to a plan, not a consumer. To apply a spike arrest to a consumer, you need to use the key attribute, which supports Expression Language.

Property	Required	Description	Type	Default
key	false	Key to identify a consumer to apply spike arresting against. Leave it empty to use the default behavior. Supports Expression Language (example: {#request.headers['x-consumer-id']}).	String	null
limit	false	Static limit on the number of requests that can be sent (this limit is used if the value > 0).	integer	0
dynamicLimit	false	Dynamic limit on the number of requests that can be sent (this limit is used if static limit = 0). The dynamic value is based on Expression Language expressions.	string	null
periodTime	true	Time duration	Integer	1
periodTimeUnit	true	Time unit (SECONDS, MINUTES)	String	SECONDS

Compatibility matrix

The following is the compatibility matrix for APIM and therate-limit policies:

Plugin Version	Supported APIM versions
1.x	Up to 3.19
2.x	3.20+

Errors

You can use the response template feature to override the default response provided by the policies. These templates must be defined at the API level (see the API Console Response Templates option in the API Proxy menu).

The error keys sent by these policies are as follows:

Key	Parameters
RATE_LIMIT_TOO_MANY_REQUESTS	limit - period_time - period_unit
QUOTA_TOO_MANY_REQUESTS	limit - period_time - period_unit
SPIKE_ARREST_TOO_MANY_REQUESTS	limit - period_time - period_unit - slice_limit - slice_period_time - slice_limit_period_unit

Changelogs

{% @github-files/github-code-block url="https://github.com/gravitee-io/gravitee-policy-ratelimit/blob/master/CHANGELOG.md" %}