# حدود المعدل والحصص

يملك Synapse سياسة حدود معدل بسيطة وقابلة للتنبؤ مصممة لمنع إساءة الاستخدام
دون أن تعيق الاستخدام المشروع.

## سياسة حد المعدل

| طريقة المصادقة | الحد | النطاق |
|-------------|-------|-------|
| Mind Key (`Authorization: Bearer`) | **لا يوجد** | لكل عقل |
| Mind Key (`?key=`) | 60 طلبًا/دقيقة | لكل IP |
| JWT (`Authorization: Bearer`) | **لا يوجد** | لكل مستخدم |
| نقاط النهاية العامة | **لا يوجد** | عام |

> [!TIP]
> **استخدم دائمًا ترويسة `Authorization: Bearer`** عندما يكون ذلك ممكنًا. ليس
> لها حد معدل. استخدم `?key=` فقط للأدوات التي لا تستطيع تعيين ترويسات مخصصة.

## ترويسات حد المعدل

عند استخدام مصادقة `?key=`، تتضمن الاستجابات ترويسات حد المعدل:

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

عند تجاوز الحد:

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

## عند بلوغ حد المعدل

إذا حصلت على 429:

1. **بدّل إلى ترويسة Authorization** (موصى به):
   ```bash
   # لا تفعل: ?key=YOUR_MIND_KEY (حد 60/دقيقة)
   curl ".../memory/recall?key=YOUR_MIND_KEY"
   
   # افعل: ترويسة Authorization (غير محدودة)
   curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall
   ```

2. **أو انتظر `Retry-After` ثانية** وأعد المحاولة.

## لماذا يوجد حد `?key=`

معامل الاستعلام `?key=` مريح للأدوات التي تفتح عناوين URL فقط (المتصفحات،
أوامر `open`)، لكن له آثارًا أمنية وأدائية:

- **الأمان:** تُسجّل معاملات الاستعلام في سجلات الوصول للخادم، وبيانات
  المتصفح، وترويسات Referer. تحديد الاستخدام يقلل من التعرض.
- **الأداء:** تتطلب مصادقة معامل الاستعلام مُحدّد معدل قائم على IP
  (بحث Redis لكل طلب)، مما يضيف زمن استجابة. مصادقة الترويسة تتجاوز هذا.
- **منع الإساءة:** يمكن مشاركة عنوان URL `?key=` المُسرّب وقصفه بالطلبات.
  يُحجم حد IP دائرة الضرر.

## الأنماط الموصى بها

### وكلاء LLM

```python
# استخدم دائمًا مصادقة الترويسة
headers = {"Authorization": f"Bearer {MIND_KEY}"}
response = requests.get(f"{URL}/memory/recall", headers=headers)
```

### أدوات المتصفح

إذا كانت أداتك تفتح عناوين URL فقط:

```bash
# مقبول للاستخدام المتقطع (أقل من 60/دقيقة)
open "https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY"

# للاستخدام المتكرر، بدّل إلى أداة تدعم الترويسات
curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall
```

### خادم MCP

خوادم MCP تستخدم دائمًا مصادقة الترويسة عبر متغير البيئة `SYNAPSE_MIND_KEY`
— لا ينطبق حد معدل.

### الاستيراد الكمي

للعمليات الكمية (مثل استيراد 1000 ذاكرة)، استخدم دائمًا مصادقة الترويسة.
الاستيراد الكمي عبر `?key=` سيبلغ حد المعدل خلال دقيقة واحدة.

## الحصص (على مستوى العقل)

لا توجد حاليًا حصص على مستوى العقل لحجم التخزين أو عدد الذكريات. جميع
الحدود على مستوى المصادقة/IP، وليس على مستوى البيانات. قد يتغير ذلك
مستقبلًا لضمان العدالة في البيئات متعددة المستأجرين.

## مراقبة الاستخدام

```bash
# تحقق من حالة حد المعدل الحالية (مع مصادقة ?key=)
curl -i "https://synapse.schaefer.zone/memory/stats?key=YOUR_MIND_KEY" | grep -i ratelimit

# المخرجات:
# X-RateLimit-Limit: 60
# X-RateLimit-Remaining: 58
# X-RateLimit-Reset: 1782567840
```

## الخطوات التالية

- [المصادقة](/docs/getting-started/authentication)
- [الأخطاء ومعالجتها](/docs/api/errors)