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

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

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

| Метод автентифікації | Ліміт | Область |
|-------------|-------|-------|
| Mind Key (`Authorization: Bearer`) | **Немає** | На mind |
| 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-only інструментів (браузери, команди
`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
# 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, а не даних. Це може змінитися
в майбутньому для справедливості в мультитенантному середовищі.

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

```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)