# Rate Limits & Kontingente

Synapse hat eine einfache, vorhersehbare Rate-Limit-Richtlinie, die Missbrauch
verhindern soll, ohne legitime Nutzung auszubremsen.

## Rate-Limit-Richtlinie

| Auth-Methode | Limit | Scope |
|---------------|-------|-------|
| Mind Key (`Authorization: Bearer`) | 120 req/min (externe IPs; unbegrenzt für vertrauenswürdige interne Netze) | Pro-Identity |
| Mind Key (`?key=`) **(veraltet)** | 60 req/min | Pro-IP |
| JWT (`Authorization: Bearer`) | 120 Anf./Min (externe IPs; unbegrenzt für vertrauenswürdige interne Netzwerke) | Pro-Nutzer |
| Öffentliche Endpunkte | **Keins** | Global |

> [!TIP]
> **Verwende immer den `Authorization: Bearer`-Header**, wenn möglich. Externe
> Bearer-Clients erhalten 120 req/min pro Identity, vertrauenswürdige interne
> Netze (Docker-Overlay, VPN, Loopback) sind unbegrenzt. Nutze `?key=` nur als
> veralteten Rückfall für Tools ohne eigene Header-Unterstützung.

## Rate-Limit-Header

Wenn du `?key=`-Auth nutzt, enthalten Antworten Rate-Limit-Header:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1782567840
```

Wenn du das Limit überschreitest:

```
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 42
Content-Type: application/json

{
  "error": "rate_limited",
  "message": "Too many requests with query-param auth. Slow down or use Authorization header."
}
```

## Wenn du ein Rate Limit triffst

Bei einer 429:

1. **Wechsle zum Authorization-Header** (empfohlen):
   ```bash
   # Don't: ?key=YOUR_MIND_KEY (60/min limit)
   curl ".../memory/recall?key=YOUR_MIND_KEY"
   
   # Do: Authorization header (unlimited)
   curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall
   ```

2. **Oder warte `Retry-After` Sekunden** und versuche es erneut.

## Warum das ?key=-Limit existiert

Der `?key=`-Query-Parameter ist praktisch für reine URL-Tools (Browser,
`open`-Befehle), ist aber veraltet und wird serverseitig über
`AUTH_QUERY_KEY_MODE` gesteuert (`deny` als Default; `allow` reaktiviert die
Query-Param-Auth). Er hat Sicherheits- und Performance-Auswirkungen:

- **Sicherheit:** Query-Parameter werden in Server-Access-Logs, Browser-Verlauf
  und Referer-Headern protokolliert. Eine Begrenzung reduziert die Exposition.
- **Performance:** Query-Parameter-Auth erfordert einen IP-basierten Rate-Limiter
  (Redis-Lookup pro Anfrage), was Latenz erzeugt. Header-Auth umgeht das.
- **Missbrauchsvermeidung:** Eine geleakte `?key=`-URL könnte geteilt und
  abgefeuert werden. Das IP-Limit begrenzt den Schadensradius.

## Empfohlene Patterns

### LLM-Agenten

```python
# Always use header auth
headers = {"Authorization": f"Bearer {MIND_KEY}"}
response = requests.get(f"{URL}/memory/recall", headers=headers)
```

### Browserbasierte Tools

Wenn dein Tool nur URLs öffnen kann:

```bash
# Veralteter Rückfall (deprecated, 60/min pro IP, gesteuert über
# AUTH_QUERY_KEY_MODE). Solche URLs niemals teilen oder als Lesezeichen
# speichern — der Key landet in Logs und Verlauf.
open "https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY"

# Empfohlen: auf ein Tool mit Header-Unterstützung wechseln
curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall
```

> [!WARNING]
> Ein Mind Key in einer URL landet in Server-Access-Logs, Browser-Verlauf und
> `Referer`-Headern. Wenn das passiert: Key sofort rotieren.

### MCP-Server

MCP-Server verwenden immer Header-Auth via `SYNAPSE_MIND_KEY`-Env-Var — kein
Rate Limit greift.

### Bulk-Importe

Für Bulk-Operationen (z. B. 1000 Memories importieren) verwende immer Header-Auth.
Bulk-Importe via `?key=` erreichen das Limit innerhalb einer Minute.

## Kontingente (Mind-Ebene)

Aktuell gibt es keine Mind-spezifischen Kontingente für Speichergröße oder
Memory-Anzahl. Alle Limits sind auf Auth/IP-Ebene, nicht auf Datenebene. Das
kann sich in Zukunft für Multi-Tenant-Fairness ändern.

## Eigene Nutzung beobachten

```bash
# Rate limit headers are attached to ?key= responses (legacy path):
curl -i "https://synapse.schaefer.zone/memory/stats?key=YOUR_MIND_KEY" | grep -i ratelimit

# Output:
# X-RateLimit-Limit: 60
# X-RateLimit-Remaining: 58
# X-RateLimit-Reset: 1782567840
```

## Nächste Schritte

- [Authentifizierung](/docs/getting-started/authentication)
- [Errors & Fehlerbehandlung](/docs/api/errors)