# Ratelimits & Quota

Synapse heeft een eenvoudig, voorspelbaar ratelimit-beleid dat is ontworpen om misbruik
te voorkomen zonder legitiem gebruik in de weg te zitten.

## Ratelimit-beleid

| Auth-methode | Limiet | Bereik |
|--------------|--------|--------|
| Mind Key (`Authorization: Bearer`) | **Geen** | Per-mind |
| Mind Key (`?key=`) | 60 aanvragen/min | Per-IP |
| JWT (`Authorization: Bearer`) | **Geen** | Per-gebruiker |
| Openbare eindpunten | **Geen** | Globaal |

> [!TIP]
> **Gebruik waar mogelijk altijd de `Authorization: Bearer`-header.** Deze heeft geen
> ratelimit. Gebruik `?key=` alleen voor tools die geen custom headers kunnen instellen.

## Ratelimit-headers

Wanneer u `?key=`-authenticatie gebruikt, bevatten responsen ratelimit-headers:

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

Wanneer u de limiet overschrijdt:

```
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."
}
```

## Als u een ratelimit raakt

Als u een 429 krijgt:

1. **Schakel over naar de Authorization-header** (aanbevolen):
   ```bash
   # Niet: ?key=YOUR_MIND_KEY (60/min limiet)
   curl ".../memory/recall?key=YOUR_MIND_KEY"
   
   # Wel: Authorization-header (onbeperkt)
   curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall
   ```

2. **Of wacht `Retry-After` seconden** en probeer opnieuw.

## Waarom de ?key= limiet bestaat

De `?key=`-queryparameter is handig voor URL-only tools (browsers,
`open`-commando's), maar heeft beveiligings- en prestatie-implicaties:

- **Beveiliging:** Queryparameters worden gelogd in server-accesslogs, browsergeschiedenis
  en Referer-headers. Beperking van gebruik verkleint de blootstelling.
- **Prestaties:** Queryparameter-authenticatie vereist een IP-gebaseerde ratelimiter
  (Redis-lookup per verzoek), wat latency toevoegt. Header-authenticatie slaat dit over.
- **Misbruikpreventie:** Een gelekte `?key=`-URL kan worden gedeeld en gebombardeerd.
  De IP-limiet beperkt de schade.

## Aanbevolen patronen

### LLM-agents

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

### Browser-gebaseerde tools

Als uw tool alleen URL's kan openen:

```bash
# OK voor incidenteel gebruik (onder 60/min)
open "https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY"

# Voor frequent gebruik, schakel over naar een tool die headers ondersteunt
curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall
```

### MCP-server

MCP-servers gebruiken altijd header-authenticatie via de `SYNAPSE_MIND_KEY`-env-var —
geen ratelimit van toepassing.

### Bulk-imports

Voor bulkoperaties (bijv. 1000 herinneringen importeren), gebruik altijd header-authenticatie.
Bulk-imports via `?key=` raken de ratelimit binnen 1 minuut.

## Quota (op mind-niveau)

Er zijn momenteel geen per-mind quota voor opslaggrootte of aantal herinneringen. Alle
limieten zitten op het auth/IP-niveau, niet op dataniveau. Dit kan in de toekomst
veranderen voor multi-tenant fairshare.

## Uw gebruik monitoren

```bash
# Controleer uw huidige ratelimit-status (met ?key=-authenticatie)
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
```

## Volgende stappen

- [Authenticatie](/docs/getting-started/authentication)
- [Fouten & Foutafhandeling](/docs/api/errors)