# REST API: limits and throttling

Adresse: https://docs.athaus.ai/en/api/v1/limits

> How many calls /v1 accepts per key and per office, which headers show the state and what to do on a 429.

Type: Reference
Last updated: 2026-11-14

`/v1` throttles with a bucket: a stock of calls at once that refills at a fixed rate. It counts per key, and a cap for the whole office applies on top.

| Bucket                             | Rate          | At once |
| ---------------------------------- | ------------- | ------- |
| Read, per key                      | 10 per second | 100     |
| Read, per office, across all keys  | 40 per second | 400     |
| Write, per key                     | 2 per second  | 60      |
| Write, per office, across all keys | 8 per second  | 240     |

The cap of the office is four times that of a key. Several keys of one office do not share one limit, but they do not run without an upper bound either.

## The headers [#the-headers]

Every response shows the state of the bucket that applies:

```http
RateLimit-Policy: "read";q=100;w=10
RateLimit: "read";r=57;t=5
```

| Part     | Meaning                                                    |
| -------- | ---------------------------------------------------------- |
| `"read"` | the name of the bucket. There are `read` and `read-office` |
| `q`      | the stock at once                                          |
| `w`      | seconds until an empty bucket is full again                |
| `r`      | this many calls are still free                             |
| `t`      | seconds until the bucket is full again                     |

The syntax follows the draft `draft-ietf-httpapi-ratelimit-headers`. It is still a draft and may change.

## When it gets too many [#when-it-gets-too-many]

The answer is `429` with `rate_limited` and the header `Retry-After` in seconds. The member `detail` names the cause: the key, the office or too many failed attempts from one address.

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 3
```

Wait that long and send the same request again. A throttled request is never executed, so repeating it is safe.

For lists, `limit=100` saves calls compared with many small pages ([Pagination](/en/api/v1/blaettern)).
