# Rate limits

How many calls a key and a company can make, what counts, and how to slow down when told to.

| Limit | Value |
| --- | --- |
| Calls a minute for each key | 60 |
| Calls a minute for each company, across all its keys | 120 |
| Calls running at once for each company | 2 |
| Rows in one page | 200 |
| Longest period | 400 days |
| Largest response | 3 MiB |
| How long call records are kept | 13 months |
| Longest key lifetime | 365 days |
| Active keys for each company | 10 |
| Notice before a breaking change | 12 months |

These numbers come from the contract, so they change here when they change in the API.

## What counts

Each minute is a rolling window. The per-key and per-company limits both apply: giving an integration more keys does not raise its company's limit.

Calls the API accepts count, and so do calls with a mistake in them, such as an invalid query or a missing scope. Calls the API refuses for a revoked, expired or unknown key, a network the key does not allow, or a limit do not count, so a busy or retrying integration does not lock itself out.

## Reading the headers

Every accepted call returns the provisional [IETF RateLimit](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/) headers:

* `RateLimit-Policy` lists the quotas: calls a minute for the key and for the company, and calls at once for the company.
* `RateLimit` gives the calls remaining (`r`) and the seconds until a call frees up (`t`), for the key and for the company.

The headers follow a draft standard, so their format can change; treat them as advice and rely on the status codes.

## When you hit a limit

A call over a limit answers 429 with [`rate_limited`](https://docs.kapiworks.com/errors/rate_limited) or [`concurrent_limit`](https://docs.kapiworks.com/errors/concurrent_limit) and a `Retry-After` header. Wait at least `Retry-After` seconds, add a small random delay, and pause every call for that company, not only the one that failed. Run one pull at a time for each company.

## Pages and periods

A page holds at most 200 rows and 3 MiB; a larger `limit` is treated as 200. A page can hold fewer rows to stay within the size, so follow `next_cursor` until it is null. A period is at most 400 days.