---
title: ratelimit.penaltybox_add
summary: null
url: >-
  https://www.fastly.com/documentation/reference/vcl/functions/rate-limiting/ratelimit-penaltybox-add
---

```
VOID ratelimit.penaltybox_add(ID pb, STRING entry, TIME ttl)
```

**Available in:** all subroutines

Add a user to a penalty box for some duration of time.

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

## Parameters

`pb` - The penalty box.

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

`ttl` - The penalty box TTL. Specifies how long a user remains penalized. Must
be between 1m and 1h, and has minute granularity (rounded to the nearest
minute).

## Return value

Upon completion, this function does not return any value.

If 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 immediately add every connecting client to the
penalty box for 5 minutes, as identified by IP address:

```vcl
penaltybox pbox { }

sub vcl_recv {
  ratelimit.penaltybox_add(pbox, client.ip, 5m);
}
```