# Rate Limits

Wie Limits, Header und Wiederholungen in der Public API funktionieren.

Authentifizierte Anfragen an die Public API sind pro Workspace rate-limitiert. Alle gültigen Keys desselben Workspaces teilen sich denselben Bucket; zusätzliche Keys erhöhen das Limit also nicht. Das öffentliche OpenAPI-Schema unter `/api/v1/openapi.json` ist nicht rate-limitiert.

Aktuelle Standardlimits:

| Fenster    | Limit          |
| ---------- | -------------- |
| Pro Minute | 60 Anfragen    |
| Pro Tag    | 1.000 Anfragen |

## Response-Header

Erfolgreiche limitierte Anfragen enthalten Header für das gerade engste Fenster:

| Header                  | Bedeutung                                             |
| ----------------------- | ----------------------------------------------------- |
| `X-RateLimit-Limit`     | Das Anfrage-Limit für das aktive Fenster              |
| `X-RateLimit-Remaining` | Verbleibende Anfragen in diesem Fenster               |
| `X-RateLimit-Reset`     | Unix-Zeitpunkt, zu dem das Fenster zurückgesetzt wird |

## Wenn du das Limit erreichst

Wenn das Minuten- oder Tagesfenster ausgeschöpft ist, gibt die API `429 TOO_MANY_REQUESTS` zurück:

```json
{
  "error": {
    "code": "TOO_MANY_REQUESTS",
    "message": "Rate limit exceeded"
  }
}
```

Die Antwort enthält zusätzlich `Retry-After` in Sekunden. Warte mindestens so lange, bevor du es erneut versuchst.

## Empfehlungen für Clients

- Behandle `Retry-After` bei `429`-Antworten als maßgeblich.
- Nutze Backoff und Jitter, wenn automatisierte Jobs Anfragen wiederholen.
- Cache stabile Reads, besonders Projektkonfiguration und Metadatenlisten.
- Paginiere Listenanfragen, statt viele sehr kleine wiederholte Anfragen zu stellen.