# Hastighetsgränser & kvoter

Synapse har en enkel, förutsägbar princip för hastighetsgränser som utformats
för att förhindra missbruk utan att vara i vägen för legitim användning.

## Princip för hastighetsgränser

| Autentiseringsmetod | Gräns | Omfattning |
|-------------|-------|-------|
| Mind Key (`Authorization: Bearer`) | **Ingen** | Per-mind |
| Mind Key (`?key=`) | 60 req/min | Per-IP |
| JWT (`Authorization: Bearer`) | **Ingen** | Per-användare |
| Publika endpoints | **Ingen** | Global |

> [!TIP]
> **Använd alltid `Authorization: Bearer`-headern** när det är möjligt. Den har
> ingen hastighetsgräns. Använd `?key=` endast för verktyg som inte kan sätta
> egna headers.

## Headers för hastighetsgränser

När ni använder `?key=`-autentisering inkluderar svar headers för hastighetsgräns:

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

När ni överskrider gränsen:

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

## När ni når en hastighetsgräns

Om ni får en 429:

1. **Byt till Authorization-header** (rekommenderas):
   ```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. **Eller vänta `Retry-After` sekunder** och försök igen.

## Varför ?key=-gränsen finns

Queryparametern `?key=` är bekväm för URL-endast-verktyg (webbläsare,
`open`-kommandon), men har säkerhets- och prestandakonsekvenser:

- **Säkerhet:** Queryparametrar loggas i serverns åtkomstloggar,
  webbläsarhistorik och Referer-headers. Begränsad användning minskar exponeringen.
- **Prestanda:** Queryparameter-autentisering kräver en IP-baserad
  hastighetsbegränsare (Redis-uppslag per begäran), vilket lägger till latens.
  Header-autentisering hoppar över detta.
- **Missbruksförebyggande:** En läckt `?key=`-URL skulle kunna delas och
  överbelastas. IP-gränsen begränsar skadeomfånget.

## Rekommenderade mönster

### LLM-agenter

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

### Webbläsarbaserade verktyg

Om ert verktyg bara kan öppna URL:er:

```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-servrar använder alltid header-autentisering via miljövariabeln
`SYNAPSE_MIND_KEY` — ingen hastighetsgräns gäller.

### Massimport

För massåtgärder (t.ex. import av 1000 minnen), använd alltid header-autentisering.
Massimport via `?key=` når hastighetsgränsen inom 1 minut.

## Kvoter (Mind-nivå)

Det finns för närvarande inga kvoter per mind för lagringsstorlek eller antal
minnen. Alla gränser är på auth/IP-nivå, inte datanivå. Detta kan ändras i
framtiden för rättvisa i miljöer med flera användare.

## Övervaka er användning

```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ästa steg

- [Autentisering](/docs/getting-started/authentication)
- [Fel & felhantering](/docs/api/errors)