# Rate limiting

The Didomi platform limits the number of requests sent to the API (<https://api.didomi.io/>) when authenticated via API keys.

Requests from Didomi SDKs are not subject to rate limiting and the limits documented in this section do not apply to the Didomi SDKs (CMP and PMP SDKs on all platforms -Web, Mobile, CTV, AMP-).

Rate limiting is used to protect the platform and to ensure the availability and performance of the Didomi API for all customers.

{% hint style="danger" %}
This page presents the current rate limits that are enforced by the Didomi API.

Those limits are subject to change at any time without prior communication to ensure the availability and performance of the Didomi API.

Rate limiting is not a commitment to honor any number of requests under any specific response time constraints and is not a service level agreement.
{% endhint %}

## Limits

Rate limits are defined globally and cannot be adjusted for specific organizations.

The following limits are currently enforced:

| Routes           | Limit                                          |
| ---------------- | ---------------------------------------------- |
| `/consents/*`    | No limit                                       |
| All other routes | 100 requests every 15 seconds per organization |

### Consents API

Didomi does not enforce any rate limit for routes under the path `/consents/*` and will not actively throttle API requests sent to those routes.

**Exception**: Requests to `GET /consents/users` and `GET /consents/users/{id}` endpoints that include the `$include_full_tree=true` query-string parameter are subject to rate limiting. These requests are intensive to process and generate large responses, so they are limited to 100 requests every 15 seconds per organization.

This is not a commitment to honor an unlimited number of requests or to enforce a specific response time. Please refer to our Service Level Agreement for more information if you need specific availability and response time commitments.

### All other API requests

For all routes other than `/consents/*`, the following rate limit is enforced: 100 requests every 15 seconds per organization.

Rate limiting is applied at the organization level. If an organization uses multiple API keys to send HTTP requests to the Didomi API, all API keys are subject to the same shared rate limit.

*Examples:*

| Scenario                                                                                                     | Throttling                                                 |
| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
| 50 requests to `GET /widgets/notices` and 5 requests to `GET /widgets/notices/configs` in a 15-second period | No throttling                                              |
| 200 requests to `GET /widgets/notices` in a 15-second period                                                 | Throttling after the first 100 requests in the time window |
| 100 requests to `GET /widgets/notices` and 200 requests to `POST /widgets/notices` in a 15-second period     | Throttling after the first 100 requests in the time window |

## HTTP responses

The following elements are added to HTTP responses from the Didomi API to help you manage rate limiting.

Rate limit header fields convey hints from the server to the clients in order to help them avoid being throttled out.

Clients MUST NOT consider the units returned in headers as a service level agreement.

In case of resource saturation, the server MAY artificially lower the returned values or not serve the request regardless of the advertised quotas.

### Throttled requests

#### Response code

When a request cannot be processed because an organization has exceeded its allocated limit, the HTTP response will be sent with the status code `429`.

This is an indication that the organization requests are being throttled and should be retried at a later time.

#### Retry-After header

When a response is sent with the status code `429`, a [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) header will be added to the HTTP response with the number of seconds that the organization should wait before sending more HTTP requests to the same route.

*Example:* `Retry-After: 15` indicates that the organization is throttled for 15 seconds and no request to the same route will be accepted for the next 15 seconds.

### All requests

All routes that are subject to rate limiting will return headers respecting the [draft 7 of the IETF RateLimit header fields for HTTP specification](https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-ratelimit-headers-07), even when the request and organization are not being actively throttled.

The following headers are added to HTTP responses:

| Header             | Format and description                                                                                                                                                                                                                                                                                                                                                                                                                            | Example                                                                                                                                                                                                                                                                                              |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RateLimit`        | <p>Format: <code>limit={limit}, remaining={remaining}, reset={reset}</code><br><br>This header provides the following information:<br>- <code>limit</code>: Maximum number of requests allowed for the route and the organization in the current time window.<br>- <code>remaining</code>: Remaining number of requests in the current time window.<br>- <code>reset</code>: Number of seconds until the remaining number of requests resets.</p> | <p><code>RateLimit: limit=100, remaining=60, reset=7</code><br><br>Indicates that the organization can send a total of 100 requests in the current time window, has 60 requests left in the current time window, and that the number of remaining requests will be set back to 100 in 7 seconds.</p> |
| `RateLimit-Policy` | <p>Format: <code>{limit};w={window}</code><br><br>This header provides the following information:<br>- <code>limit</code>: Maximum number of requests allowed for the route and the organization in the current time window.<br>- <code>window</code>: Time interval in seconds on which the limit is applied.</p>                                                                                                                                | <p><code>RateLimit-Policy: 100;w=15</code><br><br>Indicates that the organization can send a total of 100 requests in every window of 15 seconds.</p>                                                                                                                                                |