{"title":"حدود المعدل والحصص","slug":"rate-limits","category":"api","summary":"سياسة حدود المعدل لواجهة Synapse API — ترويسة Bearer (غير محدودة)، ?key= (60/دقيقة)، نقاط النهاية العامة.","audience":["human","llm"],"tags":["api","rate-limits","quotas","throttling"],"difficulty":"beginner","updated":"2026-06-27","word_count":317,"read_minutes":2,"llm_context":"Mind Key (Authorization: Bearer header) → NO rate limit\nMind Key (?key= query param) → 60 req/min per IP\nJWT (Authorization: Bearer header) → NO rate limit\nPublic endpoints (/tools/*, /docs, /health, /endpoints) → NO rate limit\nRate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After\nRecommendation: ALWAYS use Authorization header. Use ?key= only for URL-only tools.\n","lang":"ar","translated":true,"requested_lang":"ar","content_markdown":"\n# حدود المعدل والحصص\n\nيملك Synapse سياسة حدود معدل بسيطة وقابلة للتنبؤ مصممة لمنع إساءة الاستخدام\nدون أن تعيق الاستخدام المشروع.\n\n## سياسة حد المعدل\n\n| طريقة المصادقة | الحد | النطاق |\n|-------------|-------|-------|\n| Mind Key (`Authorization: Bearer`) | **لا يوجد** | لكل عقل |\n| Mind Key (`?key=`) | 60 طلبًا/دقيقة | لكل IP |\n| JWT (`Authorization: Bearer`) | **لا يوجد** | لكل مستخدم |\n| نقاط النهاية العامة | **لا يوجد** | عام |\n\n> [!TIP]\n> **استخدم دائمًا ترويسة `Authorization: Bearer`** عندما يكون ذلك ممكنًا. ليس\n> لها حد معدل. استخدم `?key=` فقط للأدوات التي لا تستطيع تعيين ترويسات مخصصة.\n\n## ترويسات حد المعدل\n\nعند استخدام مصادقة `?key=`، تتضمن الاستجابات ترويسات حد المعدل:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nX-RateLimit-Reset: 1782567840\n```\n\nعند تجاوز الحد:\n\n```\nHTTP/1.1 429 Too Many Requests\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42\nContent-Type: application/json\n\n{\n  \"statusCode\": 429,\n  \"error\": \"Too Many Requests\",\n  \"message\": \"Rate limit exceeded. Use Authorization header for unlimited access.\"\n}\n```\n\n## عند بلوغ حد المعدل\n\nإذا حصلت على 429:\n\n1. **بدّل إلى ترويسة Authorization** (موصى به):\n   ```bash\n   # لا تفعل: ?key=YOUR_MIND_KEY (حد 60/دقيقة)\n   curl \".../memory/recall?key=YOUR_MIND_KEY\"\n   \n   # افعل: ترويسة Authorization (غير محدودة)\n   curl -H \"Authorization: Bearer YOUR_MIND_KEY\" .../memory/recall\n   ```\n\n2. **أو انتظر `Retry-After` ثانية** وأعد المحاولة.\n\n## لماذا يوجد حد `?key=`\n\nمعامل الاستعلام `?key=` مريح للأدوات التي تفتح عناوين URL فقط (المتصفحات،\nأوامر `open`)، لكن له آثارًا أمنية وأدائية:\n\n- **الأمان:** تُسجّل معاملات الاستعلام في سجلات الوصول للخادم، وبيانات\n  المتصفح، وترويسات Referer. تحديد الاستخدام يقلل من التعرض.\n- **الأداء:** تتطلب مصادقة معامل الاستعلام مُحدّد معدل قائم على IP\n  (بحث Redis لكل طلب)، مما يضيف زمن استجابة. مصادقة الترويسة تتجاوز هذا.\n- **منع الإساءة:** يمكن مشاركة عنوان URL `?key=` المُسرّب وقصفه بالطلبات.\n  يُحجم حد IP دائرة الضرر.\n\n## الأنماط الموصى بها\n\n### وكلاء LLM\n\n```python\n# استخدم دائمًا مصادقة الترويسة\nheaders = {\"Authorization\": f\"Bearer {MIND_KEY}\"}\nresponse = requests.get(f\"{URL}/memory/recall\", headers=headers)\n```\n\n### أدوات المتصفح\n\nإذا كانت أداتك تفتح عناوين URL فقط:\n\n```bash\n# مقبول للاستخدام المتقطع (أقل من 60/دقيقة)\nopen \"https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY\"\n\n# للاستخدام المتكرر، بدّل إلى أداة تدعم الترويسات\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" .../memory/recall\n```\n\n### خادم MCP\n\nخوادم MCP تستخدم دائمًا مصادقة الترويسة عبر متغير البيئة `SYNAPSE_MIND_KEY`\n— لا ينطبق حد معدل.\n\n### الاستيراد الكمي\n\nللعمليات الكمية (مثل استيراد 1000 ذاكرة)، استخدم دائمًا مصادقة الترويسة.\nالاستيراد الكمي عبر `?key=` سيبلغ حد المعدل خلال دقيقة واحدة.\n\n## الحصص (على مستوى العقل)\n\nلا توجد حاليًا حصص على مستوى العقل لحجم التخزين أو عدد الذكريات. جميع\nالحدود على مستوى المصادقة/IP، وليس على مستوى البيانات. قد يتغير ذلك\nمستقبلًا لضمان العدالة في البيئات متعددة المستأجرين.\n\n## مراقبة الاستخدام\n\n```bash\n# تحقق من حالة حد المعدل الحالية (مع مصادقة ?key=)\ncurl -i \"https://synapse.schaefer.zone/memory/stats?key=YOUR_MIND_KEY\" | grep -i ratelimit\n\n# المخرجات:\n# X-RateLimit-Limit: 60\n# X-RateLimit-Remaining: 58\n# X-RateLimit-Reset: 1782567840\n```\n\n## الخطوات التالية\n\n- [المصادقة](/docs/getting-started/authentication)\n- [الأخطاء ومعالجتها](/docs/api/errors)\n","content_html":"<h1>حدود المعدل والحصص</h1>\n<p>يملك Synapse سياسة حدود معدل بسيطة وقابلة للتنبؤ مصممة لمنع إساءة الاستخدام\nدون أن تعيق الاستخدام المشروع.</p>\n<h2>سياسة حد المعدل</h2>\n<table>\n<thead>\n<tr>\n<th>طريقة المصادقة</th>\n<th>الحد</th>\n<th>النطاق</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Mind Key (<code>Authorization: Bearer</code>)</td>\n<td><strong>لا يوجد</strong></td>\n<td>لكل عقل</td>\n</tr>\n<tr>\n<td>Mind Key (<code>?key=</code>)</td>\n<td>60 طلبًا/دقيقة</td>\n<td>لكل IP</td>\n</tr>\n<tr>\n<td>JWT (<code>Authorization: Bearer</code>)</td>\n<td><strong>لا يوجد</strong></td>\n<td>لكل مستخدم</td>\n</tr>\n<tr>\n<td>نقاط النهاية العامة</td>\n<td><strong>لا يوجد</strong></td>\n<td>عام</td>\n</tr>\n</tbody></table>\n<div class=\"callout callout-ok\">**استخدم دائمًا ترويسة `Authorization: Bearer`** عندما يكون ذلك ممكنًا. ليس\nلها حد معدل. استخدم `?key=` فقط للأدوات التي لا تستطيع تعيين ترويسات مخصصة.</div><h2>ترويسات حد المعدل</h2>\n<p>عند استخدام مصادقة <code>?key=</code>، تتضمن الاستجابات ترويسات حد المعدل:</p>\n<pre><code class=\"hljs language-plaintext\">X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nX-RateLimit-Reset: 1782567840</code></pre><p>عند تجاوز الحد:</p>\n<pre><code class=\"hljs language-plaintext\">HTTP/1.1 429 Too Many Requests\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42\nContent-Type: application/json\n\n{\n  &quot;statusCode&quot;: 429,\n  &quot;error&quot;: &quot;Too Many Requests&quot;,\n  &quot;message&quot;: &quot;Rate limit exceeded. Use Authorization header for unlimited access.&quot;\n}</code></pre><h2>عند بلوغ حد المعدل</h2>\n<p>إذا حصلت على 429:</p>\n<ol>\n<li><p><strong>بدّل إلى ترويسة Authorization</strong> (موصى به):</p>\n<pre><code class=\"hljs language-bash\"><span class=\"hljs-comment\"># لا تفعل: ?key=YOUR_MIND_KEY (حد 60/دقيقة)</span>\ncurl <span class=\"hljs-string\">&quot;.../memory/recall?key=YOUR_MIND_KEY&quot;</span>\n\n<span class=\"hljs-comment\"># افعل: ترويسة Authorization (غير محدودة)</span>\ncurl -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_MIND_KEY&quot;</span> .../memory/recall</code></pre></li>\n<li><p><strong>أو انتظر <code>Retry-After</code> ثانية</strong> وأعد المحاولة.</p>\n</li>\n</ol>\n<h2>لماذا يوجد حد <code>?key=</code></h2>\n<p>معامل الاستعلام <code>?key=</code> مريح للأدوات التي تفتح عناوين URL فقط (المتصفحات،\nأوامر <code>open</code>)، لكن له آثارًا أمنية وأدائية:</p>\n<ul>\n<li><strong>الأمان:</strong> تُسجّل معاملات الاستعلام في سجلات الوصول للخادم، وبيانات\nالمتصفح، وترويسات Referer. تحديد الاستخدام يقلل من التعرض.</li>\n<li><strong>الأداء:</strong> تتطلب مصادقة معامل الاستعلام مُحدّد معدل قائم على IP\n(بحث Redis لكل طلب)، مما يضيف زمن استجابة. مصادقة الترويسة تتجاوز هذا.</li>\n<li><strong>منع الإساءة:</strong> يمكن مشاركة عنوان URL <code>?key=</code> المُسرّب وقصفه بالطلبات.\nيُحجم حد IP دائرة الضرر.</li>\n</ul>\n<h2>الأنماط الموصى بها</h2>\n<h3>وكلاء LLM</h3>\n<pre><code class=\"hljs language-python\"><span class=\"hljs-comment\"># استخدم دائمًا مصادقة الترويسة</span>\nheaders = {<span class=\"hljs-string\">&quot;Authorization&quot;</span>: <span class=\"hljs-string\">f&quot;Bearer <span class=\"hljs-subst\">{MIND_KEY}</span>&quot;</span>}\nresponse = requests.get(<span class=\"hljs-string\">f&quot;<span class=\"hljs-subst\">{URL}</span>/memory/recall&quot;</span>, headers=headers)</code></pre><h3>أدوات المتصفح</h3>\n<p>إذا كانت أداتك تفتح عناوين URL فقط:</p>\n<pre><code class=\"hljs language-bash\"><span class=\"hljs-comment\"># مقبول للاستخدام المتقطع (أقل من 60/دقيقة)</span>\nopen <span class=\"hljs-string\">&quot;https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY&quot;</span>\n\n<span class=\"hljs-comment\"># للاستخدام المتكرر، بدّل إلى أداة تدعم الترويسات</span>\ncurl -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_MIND_KEY&quot;</span> .../memory/recall</code></pre><h3>خادم MCP</h3>\n<p>خوادم MCP تستخدم دائمًا مصادقة الترويسة عبر متغير البيئة <code>SYNAPSE_MIND_KEY</code>\n— لا ينطبق حد معدل.</p>\n<h3>الاستيراد الكمي</h3>\n<p>للعمليات الكمية (مثل استيراد 1000 ذاكرة)، استخدم دائمًا مصادقة الترويسة.\nالاستيراد الكمي عبر <code>?key=</code> سيبلغ حد المعدل خلال دقيقة واحدة.</p>\n<h2>الحصص (على مستوى العقل)</h2>\n<p>لا توجد حاليًا حصص على مستوى العقل لحجم التخزين أو عدد الذكريات. جميع\nالحدود على مستوى المصادقة/IP، وليس على مستوى البيانات. قد يتغير ذلك\nمستقبلًا لضمان العدالة في البيئات متعددة المستأجرين.</p>\n<h2>مراقبة الاستخدام</h2>\n<pre><code class=\"hljs language-bash\"><span class=\"hljs-comment\"># تحقق من حالة حد المعدل الحالية (مع مصادقة ?key=)</span>\ncurl -i <span class=\"hljs-string\">&quot;https://synapse.schaefer.zone/memory/stats?key=YOUR_MIND_KEY&quot;</span> | grep -i ratelimit\n\n<span class=\"hljs-comment\"># المخرجات:</span>\n<span class=\"hljs-comment\"># X-RateLimit-Limit: 60</span>\n<span class=\"hljs-comment\"># X-RateLimit-Remaining: 58</span>\n<span class=\"hljs-comment\"># X-RateLimit-Reset: 1782567840</span></code></pre><h2>الخطوات التالية</h2>\n<ul>\n<li><a href=\"/docs/getting-started/authentication\">المصادقة</a></li>\n<li><a href=\"/docs/api/errors\">الأخطاء ومعالجتها</a></li>\n</ul>\n","urls":{"html":"/docs/api/rate-limits","text":"/docs/api/rate-limits?format=text","json":"/docs/api/rate-limits?format=json","llm":"/docs/api/rate-limits?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}