# 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`) | **Keins** | Pro-Mind |
| Mind Key (`?key=`) | 60 req/min | Pro-IP |
| JWT (`Authorization: Bearer`) | **Keins** | Pro-Nutzer |
| Öffentliche Endpunkte | **Keins** | Global |

> [!TIP]
> **Verwende immer den `Authorization: Bearer`-Header**, wenn möglich. Er hat
> kein Rate Limit. Nutze `?key=` nur für Tools, die keine eigenen Header setzen
> können.

## 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

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Use Authorization header for unlimited access."
}
```

## 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), hat aber 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
# OK for occasional use (under 60/min)
open "https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY"

# For frequent use, switch to a tool that supports headers
curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall
```

### 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
# Check your current rate limit status (with ?key= auth)
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)