Was this helpful?

A significant challenge to the maintenance of healthy APIs is traffic control. APIs consumed by heterogenous client apps are vulnerable to performance lags and downtime caused by the sudden influx of request messages, whether caused by malicious attacks, buggy apps, or seasonality.

Policies of type SpikeArrest throttle the number of requests forwarded from the point in the processing Flow where the Policy is attached a s processing Step. You can attach a SpikeArrest policy at the ProxyEndpoint request Flow to limit inbound requests. You can also attach the SpikeArrest policy at the TargetEndpoint request Flow to limit request forwarded to the backend service.

For example, if you define the SpikeArrest policy to enforce a limit of 100 messages per second, the API Platform enforces that policy by throttling any requests that exceed the 1 message every 10 milliseconds limit.

The SpikeArrest policy 'smooths' the rate limit by dividing the number of requests by the interval defined in the policy into 10 millisecond intervals.

The API Platform supports both SpikeArrest and Quota. The two policy types support different, though related, use cases:

  • SpikeArrest smooths inflow request patterns over short intervals to ensure that demand does not outstrip capacity.
  • Quota limits the number of API requests that each app can submit over a longer time interval. Quotas are generally tied to an app's consumer key, ensuring that a specific app is limited to an approved number of requests.

It is very common to combine SpikeArrest and Quota policies--the SpikeArrest prevents bursts over short intervals, while Quotas enforce longer term consumption limits.


5 per second

<SpikeArrest name="SpikeArrest">

12 per minute

<SpikeArrest name="SpikeArrest">

12 per minute with message weight reference

<SpikeArrest name="SpikeArrest">
  <Identifier ref="request.header.ID" />
  <MessageWeight ref="request.header.weight" />

Configuring a SpikeArrest policy

Configure your SpikeArrest policy using the following elements.

Field Name Description
Rate Specifies the rate at which to limit the traffic spike (or burst).
Valid value: integer per <min> or <sec>.
Identifier or client identifier (Optional) Variable used for uniquely identifying the client.
Message weight (Optional) Specifies the weighting defined for each message.
Message weight is used to modify the impact of a single request on the calculation of the SpikeArrest limit. Message weight can be set by variables based on HTTP headers, query parameters, or message body content. For example, if the SpikeArrest Rate is 10pm, and an app submits requests with weight 2, then only 5 messages per minute are permitted from that app.

SpikeArrest Flow variables

When a Spike Arrest policy executes, the following Flow variables are populated.

For more information about Flow variables, see Variables reference.

Variable Type Permission Description
ratelimit.{policy_name}.allowed.count Long Read-Only Returns the allowed limit count
ratelimit.{policy_name}.used.count Long Read-Only Returns the limit used in the counter
ratelimit.{policy_name}.exceed.count Long Read-Only Returns the count exceeds the limit in the current counter
ratelimit.{policy_name}.expiry.time Long Read-Only Returns the time in milliseconds based on which the limit expires and new counter starts

Policy-specific error codes

The default format for error codes returned by Policies is:

  "code" : " {ErrorCode} ",
  "message" : " {Error message} ",
  "contexts" : [ ]
Error Code Message
SpikeArrestViolationSpike arrest violation. Allowed rate : {0}
InvalidMessageWeightInvalid message weight value {0}
ErrorLoadingPropertiesError loading rate limit properties from {0}
InvalidAllowedRateInvalid spike arrest rate {0}.
FailedToResolveSpikeArrestRateFailed to resolve Spike Arrest Rate reference {0} in SpikeArrest policy {1}

Policy schema

Each policy type is defined by an XML schema (.xsd). For reference, policy schemas are available on GitHub.


When would one use SpikeArrest, versus Quota?

As mentioned in the page also. We should use SpikeArrest when we want to prevents bursts over short intervals, while Quotas enforce longer term consumption limits.

We're using a spikearrest policy but we don't understand how is working.
The spike arrest configuration is the following:


Reading the documentation, we understand that if we call more than 5 times
this flow in a minute, the policy will fail in the calls after the 5th. But,
when we tested it with 10 calls in less than 10 seconds, the policy accepts
the first two calls and fails in the next calls.
Can you explain us why is this happening? Can this be related to that the
environment has 2 message processors and 2 routers?

Hi Julian - Please take a look at the second and third (light bulb)
paragraphs at the top of the topic for a description of the behavior, where
your setting is actually divided into milliseconds. If you've got further
questions, I encourage you to post them to stackoverflow and use the Apigee
tag: http://stackoverflow.com/questions/tagged/apigee. Thanks, Floyd


Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.