Лимиты запросов и квоты

В 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 (рекомендуется):

   # Don't: ?key=YOUR_MIND_KEY (60/min limit)
   curl ".../memory/recall?key=YOUR_MIND_KEY"
   
   # Do: Authorization header (unlimited)
   curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall

2. Или подождите Retry-After секунд и повторите запрос.

Почему для ?key= существует лимит

Query-параметр ?key= удобен для инструментов, работающих только с URL (браузеры, команда open), но имеет последствия для безопасности и производительности:

• Безопасность: Query-параметры попадают в журналы доступа сервера, историю браузера и заголовки Referer. Ограничение использования снижает риски.
• Производительность: Аутентификация через query-параметр требует лимитера по IP (Redis-запрос на каждый запрос), что добавляет задержку. Header-auth обходит это.
• Предотвращение злоупотреблений: Утёкший URL с ?key= могут расшарить и закидать запросами. Лимит по IP ограничивает масштаб ущерба.

Рекомендуемые паттерны

LLM-агенты

# Always use header auth
headers = {"Authorization": f"Bearer {MIND_KEY}"}
response = requests.get(f"{URL}/memory/recall", headers=headers)

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

Если ваш инструмент может только открывать URL:

# OK for occasional use (under 60/min)
open "https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY"

# For frequent use, switch to a tool that supports headers
curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall

MCP-сервер

MCP-серверы всегда используют header-auth через переменную окружения SYNAPSE_MIND_KEY — лимит не применяется.

Массовый импорт

Для массовых операций (например, импорт 1000 воспоминаний) всегда используйте header-auth. Массовый импорт через ?key= упрётся в лимит менее чем за минуту.

Квоты (на уровне mind)

В настоящее время квоты на размер хранилища или количество воспоминаний на mind отсутствуют. Все лимиты применяются на уровне аутентификации/IP, а не данных. Это может измениться в будущем для обеспечения справедливости в multi-tenant-среде.

Мониторинг использования

# Check your current rate limit status (with ?key= auth)
curl -i "https://synapse.schaefer.zone/memory/stats?key=YOUR_MIND_KEY" | grep -i ratelimit

# Output:
# X-RateLimit-Limit: 60
# X-RateLimit-Remaining: 58
# X-RateLimit-Reset: 1782567840

Следующие шаги

• Аутентификация
• Ошибки и обработка ошибок