1. Home
2. Reference documentation
3. VCL reference
4. Functions
5. Rate limiting

Available inall subroutines.

Increment an entry in a ratecounter and and check if the client has exceeded some average number of requests per second.

For rate limiting purposes, consider using the ratelimit.check_rate and ratelimit.check_rates functions instead, which correctly handle the necessary details.

Parameters

rc - The ratecounter that tracks requests. When a user makes a request, a ratecounter tracks that users average rate of requests over time.

entry - The entry to keep track of. Typically client.ip, and any associated metadata. An entry can be, at maximum, 256 bytes long.

delta - The integer value to increment the entry in the rate counter by. Typically, a value of 1 is used. The value must be between 0 and 1000.

Return value

Upon completion, this function returns an integer representing the total number of estimated increments for entry, received in the given POP, over the last 1 minute.

In the event an error occurs, the default return value is false; therefore errors (via fastly.error) must be handled specifically.

Errors

If the given entry is longer than 256 bytes, then false is returned, and fastly.error is set to EINVAL.

Example

The following example will increment the entry in the ratecounter rc by 10 for every response delivered to the client, as identified by their IP. It will also set the HTTP header X-Last-60s-Hits to contain the total hits seen for that IP over the last minute.

ratecounter rc { }

sub vcl_deliver {
  declare local var.last_minute INTEGER;
  set var.last_minute = ratelimit.ratecounter_increment(rc, client.ip, 10);
  set resp.http.X-Last-60s-Hits = var.last_minute;
}

Try it out

ratelimit.ratecounter_increment is used in the following code examples. Examples apply VCL to real-world use cases and can be deployed as they are, or adapted for your own service. See the full list of code examples for more inspiration.

Click RUN on a sample below to provision a Fastly service, execute the code on Fastly, and see how the function behaves.