# Limites de débit & quotas

Synapse a une politique de limites de débit simple et prévisible, conçue pour
prévenir les abus sans gêner les usages légitimes.

## Politique de limites de débit

| Méthode d'auth | Limite | Portée |
|-------------|-------|-------|
| Mind Key (`Authorization: Bearer`) | **Aucune** | Par mind |
| Mind Key (`?key=`) | 60 req/min | Par IP |
| JWT (`Authorization: Bearer`) | **Aucune** | Par utilisateur |
| Endpoints publics | **Aucune** | Globale |

> [!TIP]
> **Utilisez toujours l'en-tête `Authorization: Bearer`** lorsque c'est possible. Il
> n'a aucune limite de débit. N'utilisez `?key=` que pour les outils qui ne peuvent
> pas définir d'en-têtes personnalisés.

## En-têtes de limite de débit

Lorsque vous utilisez l'authentification `?key=`, les réponses incluent des en-têtes
de limite de débit :

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

Lorsque vous dépassez la limite :

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

## Que faire en cas de limite de débit

Si vous obtenez un 429 :

1. **Passez à l'en-tête Authorization** (recommandé) :
   ```bash
   # À éviter : ?key=YOUR_MIND_KEY (limite 60/min)
   curl ".../memory/recall?key=YOUR_MIND_KEY"
   
   # À faire : en-tête Authorization (illimité)
   curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall
   ```

2. **Ou attendez `Retry-After` secondes** et réessayez.

## Pourquoi la limite ?key= existe

Le paramètre de requête `?key=` est pratique pour les outils n'utilisant que des URLs
(navigateurs, commandes `open`), mais il a des implications de sécurité et de
performance :

- **Sécurité :** Les paramètres de requête sont consignés dans les journaux d'accès
  serveur, l'historique du navigateur et les en-têtes Referer. Limiter l'usage réduit
  l'exposition.
- **Performance :** L'authentification par paramètre de requête nécessite un
  limiteur de débit basé sur l'IP (recherche Redis par requête), ce qui ajoute de la
  latence. L'authentification par en-tête l'évite.
- **Prévention des abus :** Une URL `?key=` fuite pourrait être partagée et martelée.
  La limite par IP contient le rayon d'impact.

## Schémas recommandés

### Agents LLM

```python
# Toujours utiliser l'authentification par en-tête
headers = {"Authorization": f"Bearer {MIND_KEY}"}
response = requests.get(f"{URL}/memory/recall", headers=headers)
```

### Outils basés sur navigateur

Si votre outil ne peut qu'ouvrir des URLs :

```bash
# OK pour un usage occasionnel (sous 60/min)
open "https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY"

# Pour un usage fréquent, passez à un outil qui prend en charge les en-têtes
curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall
```

### Serveur MCP

Les serveurs MCP utilisent toujours l'authentification par en-tête via la variable
d'environnement `SYNAPSE_MIND_KEY` — aucune limite de débit ne s'applique.

### Imports en masse

Pour les opérations en masse (ex. import de 1000 mémoires), utilisez toujours
l'authentification par en-tête. Les imports en masse via `?key=` atteindront la
limite de débit en moins d'une minute.

## Quotas (niveau mind)

Il n'y a actuellement aucun quota par mind sur la taille de stockage ou le nombre de
mémoires. Toutes les limites se situent au niveau auth/IP, pas au niveau des données.
Cela pourrait changer à l'avenir pour l'équité multi-tenant.

## Surveiller votre utilisation

```bash
# Vérifiez votre statut actuel de limite de débit (avec auth ?key=)
curl -i "https://synapse.schaefer.zone/memory/stats?key=YOUR_MIND_KEY" | grep -i ratelimit

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

## Prochaines étapes

- [Authentification](/docs/getting-started/authentication)
- [Erreurs & gestion des erreurs](/docs/api/errors)