# REST-API: Limits und Drossel

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

> Wie viele Aufrufe /v1 je Schlüssel und je Büro annimmt, welche Köpfe den Stand zeigen und was bei einem 429 zu tun ist.

Typ: Referenz
Zuletzt aktualisiert: 2026-11-14

`/v1` drosselt nach dem Eimer-Prinzip: ein Vorrat an Aufrufen auf einmal, der mit fester Rate nachläuft. Gezählt wird je Schlüssel, und zusätzlich gilt ein Deckel für das ganze Büro.

| Eimer                                   | Rate          | Auf einmal |
| --------------------------------------- | ------------- | ---------- |
| Lesen, je Schlüssel                     | 10 je Sekunde | 100        |
| Lesen, je Büro, über alle Schlüssel     | 40 je Sekunde | 400        |
| Schreiben, je Schlüssel                 | 2 je Sekunde  | 60         |
| Schreiben, je Büro, über alle Schlüssel | 8 je Sekunde  | 240        |

Der Deckel des Büros ist das Vierfache des Schlüssels. So teilen sich mehrere Schlüssel eines Büros die Grenze nicht, laufen aber auch nicht ohne Obergrenze.

## Die Köpfe [#die-köpfe]

Jede Antwort zeigt den Stand des Eimers, der gerade gilt:

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

| Teil     | Bedeutung                                             |
| -------- | ----------------------------------------------------- |
| `"read"` | der Name des Eimers. Es gibt `read` und `read-office` |
| `q`      | der Vorrat auf einmal                                 |
| `w`      | Sekunden, bis ein leerer Eimer wieder voll ist        |
| `r`      | so viele Aufrufe sind noch frei                       |
| `t`      | Sekunden, bis der Eimer wieder voll ist               |

Die Syntax folgt dem Entwurf `draft-ietf-httpapi-ratelimit-headers`. Er ist noch ein Entwurf und kann sich ändern.

## Wenn es zu viele werden [#wenn-es-zu-viele-werden]

Die Antwort ist `429` mit `rate_limited` und dem Kopf `Retry-After` in Sekunden. Das Mitglied `detail` nennt die Ursache: den Schlüssel, das Büro oder zu viele Fehlversuche von einer Adresse.

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

Warte so lange und sende dieselbe Anfrage noch einmal. Eine gedrosselte Anfrage wird nie ausgeführt, du kannst sie also gefahrlos wiederholen.

Bei Listen spart `limit=100` Aufrufe gegenüber vielen kleinen Seiten ([Blättern](/api/v1/blaettern)).
