# Limites de taxa e cotas

O Synapse tem uma política de limite de taxa simples e previsível, projetada
para evitar abuso sem atrapalhar o uso legítimo.

## Política de limite de taxa

| Método de auth | Limite | Escopo |
|----------------|--------|--------|
| Mind Key (`Authorization: Bearer`) | **Nenhum** | Por mind |
| Mind Key (`?key=`) | 60 req/min | Por IP |
| JWT (`Authorization: Bearer`) | **Nenhum** | Por usuário |
| Endpoints públicos | **Nenhum** | Global |

> [!TIP]
> **Sempre use o cabeçalho `Authorization: Bearer`** quando possível. Ele não
> tem limite de taxa. Use `?key=` apenas para ferramentas que não conseguem
> definir cabeçalhos personalizados.

## Cabeçalhos de limite de taxa

Quando você usa auth via `?key=`, as respostas incluem cabeçalhos de limite:

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

Quando você excede o limite:

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

## Quando você atinge um limite de taxa

Se você recebe um 429:

1. **Mude para o cabeçalho Authorization** (recomendado):
   ```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. **Ou aguarde `Retry-After` segundos** e tente novamente.

## Por que o limite de ?key= existe

O parâmetro de consulta `?key=` é conveniente para ferramentas somente-URL
(navegadores, comandos `open`), mas tem implicações de segurança e desempenho:

- **Segurança:** Parâmetros de consulta são registrados em logs de acesso do
  servidor, histórico do navegador e cabeçalhos Referer. Limitar o uso reduz a
  exposição.
- **Desempenho:** Auth por parâmetro de consulta requer um limitador de taxa
  baseado em IP (lookup Redis por requisição), o que adiciona latência. Auth
  por cabeçalho pula isso.
- **Prevenção de abuso:** Uma URL `?key=` vazada poderia ser compartilhada e
  bombardeada. O limite por IP contém o raio de explosão.

## Padrões recomendados

### Agentes LLM

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

### Ferramentas baseadas em navegador

Se sua ferramenta só consegue abrir URLs:

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

### Servidor MCP

Servidores MCP sempre usam auth por cabeçalho via variável de ambiente
`SYNAPSE_MIND_KEY` — nenhum limite de taxa se aplica.

### Importações em massa

Para operações em massa (ex.: importar 1000 memórias), sempre use auth por
cabeçalho. Importações em massa via `?key=` atingirão o limite de taxa em menos
de 1 minuto.

## Cotas (nível de mind)

Atualmente não há cotas por mind em tamanho de armazenamento ou contagem de
memórias. Todos os limites são em nível de auth/IP, não de dados. Isso pode
mudar no futuro para justiça multi-tenant.

## Monitorando seu uso

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

## Próximos passos

- [Autenticação](/docs/getting-started/authentication)
- [Erros e tratamento de erros](/docs/api/errors)