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

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é) :

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

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

# 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

# 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
• Erreurs & gestion des erreurs