# Rate Limiting

NOTE: For Reporting API rate limiting is now enabled. In case of other endpoints it is enabled in reporting-only mode. Requests rejection (429 HTTP status code response) in all endpoints will be enabled soon.

In order to make Placewise API stable and fair for everyone, our APIs are rate-limited.

## Algorithm

Placewise uses [token bucket algorithm](https://en.wikipedia.org/wiki/Token_bucket) to handle rate-limiting.

* Each customer has a bucket which has defined capacity
* Each API removes defined in API specification number of tokens from the bucket
* Each second tokens are added to the bucket until bucket reaches the capacity
* When bucket is empty, API client will receive `429 Too Many Requests` HTTP errors until there is a free space in the bucket

## Buckets

There are 4 different buckets which depend on the type of API request and customer context.

### Owner

| **Owner** | **Description**  |
| --- | --- |
| Customer | Requests which is done in context of single customer |
| Organization | Requests which is done in context of organization or multiple customers |

### Type

| **Bucket type** | **Description** |
| --- | --- |
| General | Main bucket used in most cases. |
| Reporting | Bucket used within `Reporting API` |

## Cost of API endpoint

The number of tokens that are removed from the bucket by the endpoint is specified in the API endpoint specification.

Most API endpoints cost `1` token.

## `Too many request` response

When the rate-limiting bucket is empty then you will receive HTTP responses with `429 Too Many Requests` HTTP status.

Response will include a `Retry-After` header with a minimum number of seconds that you need to wait before the next request is not rate-limited.

## Additional response headers

When the request is validated through rate-limiting solutions then following HTTP Headers will be added to the response:

* `ratelimit-bucket` - Identifier of bucket which was used by given request.
* `ratelimit-remaining` - How many tokens are left in the bucket. Value is an integer and can be below 0.
* `ratelimit-cost` - How much tokens were used by given request.

## Details

* `Reporting API` uses a different number of tokens based on requested data. See [Reporting API Introduction](https://docs.mpc.placewise.com/doc-343952) for more details.