# Rate Limits & Kontingente
SUMMARY: Rate-Limit-Richtlinien für die Synapse-API — Bearer-Header (empfohlen), ?key= veraltet (60/min), öffentliche Endpunkte.

KEY CONTEXT:
Mind Key (Authorization: Bearer header) → 120 req/min from external IPs; unlimited for trusted internal networks
Mind Key (?key= query param) → 60 req/min per IP (deprecated; gated by AUTH_QUERY_KEY_MODE, default: deny)
JWT (Authorization: Bearer header) → 120 req/min from external IPs; unlimited for trusted internal networks
Public endpoints (/tools/*, /docs, /health, /endpoints) → NO rate limit
Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After
Recommendation: ALWAYS use Authorization header. Use ?key= only for URL-only tools.

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 () | 120 req/min (externe IPs; unbegrenzt für vertrauenswürdige interne Netze) | Pro-Identity |
| Mind Key () (veraltet) | 60 req/min | Pro-IP |
| JWT () | 120 Anf./Min (externe IPs; unbegrenzt für vertrauenswürdige interne Netzwerke) | Pro-Nutzer |
| Öffentliche Endpunkte | Keins | Global |
> [!TIP]
> Verwende immer den -Header, wenn möglich. Externe
> Bearer-Clients erhalten 120 req/min pro Identity, vertrauenswürdige interne
> Netze (Docker-Overlay, VPN, Loopback) sind unbegrenzt. Nutze  nur als
> veralteten Rückfall für Tools ohne eigene Header-Unterstützung.
Rate-Limit-Header
Wenn du -Auth nutzt, enthalten Antworten Rate-Limit-Header:
[CODE BLOCK]
Wenn du das Limit überschreitest:
[CODE BLOCK]
Wenn du ein Rate Limit triffst
Bei einer 429:
1. Wechsle zum Authorization-Header (empfohlen):
   [CODE BLOCK]
2. Oder warte  Sekunden und versuche es erneut.
Warum das ?key=-Limit existiert
Der -Query-Parameter ist praktisch für reine URL-Tools (Browser,
-Befehle), ist aber veraltet und wird serverseitig über
 gesteuert ( als Default;  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 -URL könnte geteilt und
  abgefeuert werden. Das IP-Limit begrenzt den Schadensradius.
Empfohlene Patterns
LLM-Agenten
[CODE BLOCK]
Browserbasierte Tools
Wenn dein Tool nur URLs öffnen kann:
[CODE BLOCK]
> [!WARNING]
> Ein Mind Key in einer URL landet in Server-Access-Logs, Browser-Verlauf und
> -Headern. Wenn das passiert: Key sofort rotieren.
MCP-Server
MCP-Server verwenden immer Header-Auth via -Env-Var — kein
Rate Limit greift.
Bulk-Importe
Für Bulk-Operationen (z. B. 1000 Memories importieren) verwende immer Header-Auth.
Bulk-Importe via  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
[CODE BLOCK]
Nächste Schritte
- Authentifizierung
- Errors & Fehlerbehandlung