{"title":"Обмеження частоти та квоти","slug":"rate-limits","category":"api","summary":"Політика обмеження частоти для API Synapse — заголовок Bearer (без обмежень), ?key= (60/хв), публічні кінцеві точки.","audience":["human","llm"],"tags":["api","rate-limits","quotas","throttling"],"difficulty":"beginner","updated":"2026-06-27","word_count":327,"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":"uk","translated":true,"requested_lang":"uk","content_markdown":"\n# Обмеження частоти та квоти\n\nSynapse має просту та передбачувану політику обмеження частоти, розроблену для\nзапобігання зловживанням, не заважаючи легітимному використанню.\n\n## Політика обмеження частоти\n\n| Метод автентифікації | Ліміт | Область |\n|-------------|-------|-------|\n| Mind Key (`Authorization: Bearer`) | **Немає** | На mind |\n| Mind Key (`?key=`) | 60 запитів/хв | На IP |\n| JWT (`Authorization: Bearer`) | **Немає** | На користувача |\n| Публічні кінцеві точки | **Немає** | Глобально |\n\n> [!TIP]\n> **Завжди використовуйте заголовок `Authorization: Bearer`**, коли це можливо.\n> Він не має обмеження частоти. Використовуйте `?key=` лише для інструментів, які\n> не можуть встановлювати власні заголовки.\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-only інструментів (браузери, команди\n`open`), але має наслідки для безпеки та продуктивності:\n\n- **Безпека:** Параметри запиту фіксуються в журналах доступу сервера, історії\n  браузера та заголовках Referer. Обмеження використання зменшує ризик викриття.\n- **Продуктивність:** Автентифікація через параметр запиту потребує обмежувача\n  частоти на основі IP (пошук у Redis на кожен запит), що додає затримку.\n  Автентифікація через заголовок пропускає це.\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# OK для випадкового використання (до 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\nMCP-сервери завжди використовують автентифікацію через заголовок за допомогою\nзмінної середовища `SYNAPSE_MIND_KEY` — обмеження частоти не застосовується.\n\n### Масовий імпорт\n\nДля масових операцій (напр. імпорт 1000 спогадів) завжди використовуйте\nавтентифікацію через заголовок. Масовий імпорт через `?key=` досягне ліміту\nпротягом 1 хвилини.\n\n## Квоти (на рівні mind)\n\nНаразі немає квот на розмір сховища або кількість спогадів для окремого mind-у.\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>На mind</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=` лише для інструментів, які\nне можуть встановлювати власні заголовки.</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>Чому існує ліміт ?key=</h2>\n<p>Параметр запиту <code>?key=</code> зручний для URL-only інструментів (браузери, команди\n<code>open</code>), але має наслідки для безпеки та продуктивності:</p>\n<ul>\n<li><strong>Безпека:</strong> Параметри запиту фіксуються в журналах доступу сервера, історії\nбраузера та заголовках Referer. Обмеження використання зменшує ризик викриття.</li>\n<li><strong>Продуктивність:</strong> Автентифікація через параметр запиту потребує обмежувача\nчастоти на основі IP (пошук у Redis на кожен запит), що додає затримку.\nАвтентифікація через заголовок пропускає це.</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\"># OK для випадкового використання (до 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-сервери завжди використовують автентифікацію через заголовок за допомогою\nзмінної середовища <code>SYNAPSE_MIND_KEY</code> — обмеження частоти не застосовується.</p>\n<h3>Масовий імпорт</h3>\n<p>Для масових операцій (напр. імпорт 1000 спогадів) завжди використовуйте\nавтентифікацію через заголовок. Масовий імпорт через <code>?key=</code> досягне ліміту\nпротягом 1 хвилини.</p>\n<h2>Квоти (на рівні mind)</h2>\n<p>Наразі немає квот на розмір сховища або кількість спогадів для окремого mind-у.\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"]}