API throttling configuration

You can configure API throttling in the API Keys and Traffic Management application. On the API throttling tab, you define throttling that increases whenever an incoming request meets the defined throttling conditions.

When setting up a throttling condition, you can select the following entities:

specific API keys
whole key collections
endpoints and resources (including HTTP method)

You can define up to 100 throttling counters per account, but a single request can increase up to 4 counters at a maximum. This means that you cannot define more than 4 throttling counters with overlapping throttling conditions.

An overlap between two throttling counters occurs when these counters' throttling conditions are defined such that one request may potentially increase both counters.

To fully understand this concept, imagine that you created the following throttling counters:

A counter that increases when a request with an API key of "12345" reaches your API network.
A counter that increases when a request with the API key of "12345" reaches a "Bookstore API".
A counter that increases when a request reaches the "Bookstore API".
A counter that increases when a request reaches an "order" resource within the "Bookstore API".

If an API consumer who identifies with the "12345" API key makes a request to the "order" resource, the request meets the conditions of each of the above counters. This causes all four counters to increase.

If you were to create another counter that increases when, for example, a GET request reaches the "order" resource, a single request could potentially increase five counters. API Gateway currently supports increasing a maximum of four counters with a single request. Therefore, any attempt to create the fifth counter with overlapping conditions would result in an error upon saving the counter definition.

A single counter may include multiple conditions that a request must meet to increase the counter. For example, you may configure a counter so that it increases when a request with an API key "12345" reaches the "Bookstore API" resource. The counter increases only if a request meets both of these conditions. This means that API calls using the "12345" API key to access APIs other than "Bookstore API" have no effect on the counter. The same goes for API calls to the "Bookstore API" that do not use the "12345" API key.

The entities that are available for selection when defining throttling conditions are associated with the access control group (ACG) that you specify when entering counter information. An ACG is a combination of Akamai contract and group with which your registered APIs and API keys are associated. If you want to select a particular registered API or API key but cannot locate it in the Throttling conditions section, it means that the entity is associated with another access control group. In such case, choose another ACG from the Access control group list and see if the entity you are looking for is available for selection.

You can set headers to indicate the throttling limit for the entire Akamai edge network in your responses to API consumers' requests. Headers provide valuable information to API consumers and API publishers about the remaining throttling limit and the maximum allowed throttling limit. API consumers may use this information to plan subsequent requests to your API. The default throttling-related headers are:

X-Throttling-Limit. Provides information about the requests-per-second limit set for a throttling counter.
X-Throttling-Rate. Provides information about the current rate which throttling is handling in the current second.

You can set up both headers such that edge servers pass them either to the client, to your origin, or both.

When an API consumer's request reaches the throttling counter limit, edge servers deny a consumer's excessive requests with a 429 "Too Many Requests" HTTP error response. You can also customize the error response as desired in the Error response customization section. This functionality mirrors the one available in API Definitions. For details, see Error response customization.