# Limity żądań i przydziały

Synapse posiada prostą i przewidywalną politykę limitów żądań, zaprojektowaną w
celu zapobiegania nadużyciom, nie blokując jednocześnie prawidłowego użytku.

## Polityka limitów żądań

| Metoda autoryzacji | Limit | Zakres |
|-------------|-------|-------|
| Mind Key (`Authorization: Bearer`) | **Brak** | Na umysł |
| Mind Key (`?key=`) | 60 żądań/min | Na IP |
| JWT (`Authorization: Bearer`) | **Brak** | Na użytkownika |
| Endpointy publiczne | **Brak** | Globalny |

> [!TIP]
> **Należy zawsze używać nagłówka `Authorization: Bearer`, gdy to możliwe.** Nie
> ma on limitu żądań. `?key=` należy stosować tylko w narzędziach, które nie
> potrafią ustawiać własnych nagłówków.

## Nagłówki limitu żądań

Gdy używana jest autoryzacja `?key=`, odpowiedzi zawierają nagłówki limitu:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1782567840
```

Po przekroczeniu limitu:

```
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."
}
```

## Po osiągnięciu limitu żądań

W przypadku otrzymania 429:

1. **Przełączyć się na nagłówek Authorization** (zalecane):
   ```bash
   # Nie: ?key=YOUR_MIND_KEY (limit 60/min)
   curl ".../memory/recall?key=YOUR_MIND_KEY"
   
   # Tak: nagłówek Authorization (bez limitu)
   curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall
   ```

2. **Lub odczekać `Retry-After` sekund** i ponowić żądanie.

## Dlaczego istnieje limit dla `?key=`

Parametr zapytania `?key=` jest wygodny dla narzędzi opartych wyłącznie na URL
(przeglądarki, polecenia `open`), ale niesie ze sobą implikacje bezpieczeństwa i
wydajności:

- **Bezpieczeństwo:** Parametry zapytania są rejestrowane w logach dostępu
  serwera, historii przeglądarki i nagłówkach Referer. Ograniczenie użycia
  zmniejsza ekspozycję.
- **Wydajność:** Autoryzacja parametrem zapytania wymaga ogranicznika opartego na
  IP (odpytanie Redis przy każdym żądaniu), co dodaje opóźnienie. Autoryzacja
  nagłówkiem pomija ten krok.
- **Zapobieganie nadużyciom:** Wyciekły URL `?key=` mógłby zostać udostępniony i
  masowo wywoływany. Limit IP ogranicza obszar rażenia.

## Zalecane wzorce

### Agenci LLM

```python
# Zawsze używać autoryzacji nagłówkiem
headers = {"Authorization": f"Bearer {MIND_KEY}"}
response = requests.get(f"{URL}/memory/recall", headers=headers)
```

### Narzędzia oparte na przeglądarce

Jeśli narzędzie potrafi tylko otwierać URL-e:

```bash
# Dopuszczalne do okazjonalnego użycia (poniżej 60/min)
open "https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY"

# Do częstego użycia przełączyć się na narzędzie obsługujące nagłówki
curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall
```

### Serwer MCP

Serwery MCP zawsze korzystają z autoryzacji nagłówkiem przez zmienną środowiskową
`SYNAPSE_MIND_KEY` — limit nie ma zastosowania.

### Importy masowe

W przypadku operacji masowych (np. import 1000 wspomnień) zawsze należy używać
autoryzacji nagłówkiem. Importy przez `?key=` osiągną limit w ciągu minuty.

## Przydziały (poziom umysłu)

Obecnie nie ma przydziałów na poziomie umysłu dotyczących rozmiaru pamięci lub
liczby wspomnień. Wszystkie limity znajdują się na poziomie autoryzacji/IP, a nie
danych. Może się to zmienić w przyszłości w celu sprawiedliwego współdzielenia
w środowisku wielodostępnym.

## Monitorowanie użycia

```bash
# Sprawdzenie aktualnego statusu limitu (z autoryzacją ?key=)
curl -i "https://synapse.schaefer.zone/memory/stats?key=YOUR_MIND_KEY" | grep -i ratelimit

# Wynik:
# X-RateLimit-Limit: 60
# X-RateLimit-Remaining: 58
# X-RateLimit-Reset: 1782567840
```

## Następne kroki

- [Autoryzacja](/docs/getting-started/authentication)
- [Błędy i ich obsługa](/docs/api/errors)