The Kukie.io API limits how many requests a key and an organisation can send, so that one integration cannot slow the service for everyone. This guide lists the limits, the headers that report them and what to do when you reach one.
Limits for every request
| What is counted | For each API key | For the organisation |
|---|---|---|
| Requests a minute, of any kind | 300 | 600 |
| Of those, requests a minute that change something (POST, PATCH, PUT and DELETE) | 60 | 120 |
| Requests running at the same time | - | 2 |
The organisation's limits count all its keys together. Reading the account returns the same figures in rate_limits, so your software can read them there.
Each limit for a minute counts in a fixed window that opens with the first counted request, and so does every limit for a longer time below. So around the end of a window, up to twice a figure can pass in a short time.
Limits of single operations
Some operations add limits of their own, for each organisation unless the table says otherwise. Most of them count only work that was done: such a limit is checked before a request and counted after it, so requests that run at the same moment can pass its figure by one. Each operation's description in the API reference says what counts against its limit.
| Operation | Limit |
|---|---|
| Create a site | 10 a minute, 300 an hour and 1,000 a day |
| Delete a site | 10 a minute and 200 a day |
| Check the banner installation | 1 a minute for each site and 60 an hour for the organisation, one check at a time |
| Start a cookie scan | 60 an hour for the organisation and 6 a day for each site, one scan of a site at a time, and at most 50 scans started through the API waiting at once |
| Read consent statistics | 10 a minute for each site and 20 a minute for the organisation |
| Copy settings to other sites | 100 target sites in a window of 5 minutes, and at most 100 target sites in one request |
| Changes that rebuild a site's banner: creating or deleting a site, a change of banner settings, texts, region rules or the accessibility widget, and moving cookies into a category | A shared budget of 60 for each window of 5 minutes, and of 24 in a minute. A change that changes nothing, or is refused, does not count. A copy of settings uses one of it for each 30 target sites or part of 30, and each target site also counts against a second budget of 200 rebuilt sites for each window of 5 minutes, which every change above shares. |
| Read the OpenAPI document | 30 a minute for each address. It needs no API key. |
The rate limit headers
A successful answer to a request sent with an API key carries two headers:
X-RateLimit-Limit: how many requests the tightest of your limits allows in its window.X-RateLimit-Remaining: how many requests are left in that window.
When you reach a limit
The API answers 429 with a Retry-After header, the number of seconds to wait:
rate_limited: you sent more requests than a limit allows. Wait the seconds inRetry-After.concurrency_limited: something has to finish first. Most often the organisation already has 2 requests running, andRetry-Afteris then 1 second. A scan start answers it too while another scan start of your organisation is running. An installation check answers it while another check is running for your organisation or for the same site, or while Kukie.io is running as many checks as it allows at once.queue_full: too many scans are waiting, either those your organisation started through the API or those of Kukie.io as a whole, or, for a scan report PDF, 10 of your organisation's PDFs are already waiting to be made. Wait the seconds inRetry-After.
A limit that all organisations share can also answer 429. That answer has Retry-After and no rate limit headers.
To stay inside the limits, send requests one after another instead of in parallel, and wait as long as Retry-After says before you try again.
Request sizes
- A request body can be up to 1,048,576 bytes (1 MiB). A larger one answers 413
payload_too_large. - A list inside a request body can have up to 200 items, unless the operation sets a smaller number.
