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

В 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
   # 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-агенты

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

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

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

```bash
# 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-среде.

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

```bash
# 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
```

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

- [Аутентификация](/docs/getting-started/authentication)
- [Ошибки и обработка ошибок](/docs/api/errors)