API rate limit action

The API Gateway runs the API rate limit action to enforce the rate limit and burst limit schemes that are defined for the target API or operation.

Rate limit scheme
A rate limit scheme controls the rate of the API transactions. A rate limit scheme defines the maximum rate that is allowed in a specified time interval and the actions to take when the limit is exceeded.
Burst limit scheme
A burst limit scheme also defines the maximum rate that is allowed in a usually shorter interval. A burst limit scheme helps prevent usage spikes within a short time span that might damage infrastructure. The burst limit takes higher priority than the rate limit, when a message arrives within an interval, the message is first checked against the burst limit scheme. When the burst limit is exceeded, the request is rejected.

For example, an API has a rate limit of 10 calls/minute and a burst limit of 3 calls/second. When the third call arrives within the first second of a 1-minute interval, the burst limit is exceeded and the call is rejected, although the 10 calls/minute rate limit is not yet reached.

The API rate limit action enforces the rate limit scheme in the following process.
  1. The API rate limit action determines the rate limit scheme to enforce.
    • If the subscriber is identified and the plan is matched during the API client identification phase, the API rate limit action checks whether the operation-level rate limit scheme is defined for the target operation.
      • When defined, the action enforces the operation-level rate limit.
      • When not defined, the action enforces the plan-level rate limit.
    • If the subscriber is not identified during the client identification phase, the API rate limit action checks whether the default rate limit is configured.
      • When configured, the action matches the default rate limit that is defined for the API collection.
      • When not configured, the request is rejected.
  2. The action enforces rate limiting.
    • If the burst limit is exceeded, no X-RateLimit-* headers but a 429 error code is returned.
    • If the burst limit is not exceeded, the action proceeds to check the rate limit.
      • When the rate limit is not exceeded, the request is processed. When the rate limit is exceeded but the hard limit setting is not enabled, the request is still processed but with a warning. In this case, the response carries the following headers.
        X-RateLimit-Limit
        The number of calls allowed per interval.
        X-RateLimit-Remaining
        The number of calls remaining in the interval before reaching the limit.
      • When the rate limit is exceeded and the hard limit setting is enabled, the request is rejected. In this case, in addition to the headers above, the response carries the following headers.
        X-RateLimit-Reset
        The number of seconds remaining until the beginning of the next interval.
        Retry-After
        The Same as X-RateLimit-Reset.