Обмеження частоти та квоти

Synapse має просту та передбачувану політику обмеження частоти, розроблену для запобігання зловживанням, не заважаючи легітимному використанню.

Політика обмеження частоти

Заголовки обмеження частоти

Коли ви використовуєте автентифікацію ?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 (рекомендовано):

   # Не робіть: ?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-only інструментів (браузери, команди open), але має наслідки для безпеки та продуктивності:

• Безпека: Параметри запиту фіксуються в журналах доступу сервера, історії браузера та заголовках Referer. Обмеження використання зменшує ризик викриття.
• Продуктивність: Автентифікація через параметр запиту потребує обмежувача частоти на основі IP (пошук у Redis на кожен запит), що додає затримку. Автентифікація через заголовок пропускає це.
• Запобігання зловживанням: Виточена URL-адреса ?key= може бути поширена та піддата масовому використанню. Ліміт на IP обмежує масштаб шкоди.

Рекомендовані шаблони

LLM-агенти

# Завжди використовуйте автентифікацію через заголовок
headers = {"Authorization": f"Bearer {MIND_KEY}"}
response = requests.get(f"{URL}/memory/recall", headers=headers)

Браузерні інструменти

Якщо ваш інструмент може лише відкривати URL:

# OK для випадкового використання (до 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= досягне ліміту протягом 1 хвилини.

Квоти (на рівні mind)

Наразі немає квот на розмір сховища або кількість спогадів для окремого mind-у. Усі обмеження діють на рівні автентифікації/IP, а не даних. Це може змінитися в майбутньому для справедливості в мультитенантному середовищі.

Моніторинг вашого використання

# Перевірте поточний стан обмеження частоти (з автентифікацією ?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

Наступні кроки

• Автентифікація
• Помилки та обробка помилок