# Erros e tratamento de erros

O Synapse usa códigos de status HTTP padrão com um formato consistente de
resposta de erro. Esta página explica como interpretar e se recuperar de erros.

## Formato de resposta de erro

Todos os erros retornam JSON com esta estrutura:

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Mind Key fehlt oder ungültig.",
  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"
}
```

| Campo | Descrição |
|-------|-----------|
| `statusCode` | Código de status HTTP |
| `error` | Nome do status HTTP |
| `message` | Descrição do erro legível para humanos |
| `docs` | URL para a documentação relevante (quando aplicável) |

## Códigos de status HTTP

### 200 OK

Sucesso. A requisição foi processada corretamente.

### 201 Created

Sucesso. Um novo recurso foi criado (ex.: `POST /memory`).

### 204 No Content

Sucesso. Sem corpo retornado (ex.: `DELETE /memory/:id`).

### 400 Bad Request

A requisição estava malformada. Causas comuns:

- Campos JSON obrigatórios ausentes
- Sintaxe JSON inválida
- Valor de enum inválido (ex.: categoria errada)

```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "category must be one of: identity, preference, fact, project, skill, mistake, context, note, credentials"
}
```

**Correção:** Confira o corpo da requisição com a documentação da API. Garanta
que todos os campos obrigatórios estão presentes e têm valores válidos.

### 401 Unauthorized

A autenticação falhou. Causas comuns:

- Cabeçalho `Authorization` ausente
- Mind Key ou JWT inválido
- Uso de Mind Key onde JWT é necessário (ou vice-versa)

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Mind Key fehlt oder ungültig.",
  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"
}
```

**Correção:** Verifique seu token. Consulte [Autenticação](/docs/getting-started/authentication).

### 403 Forbidden

Você está autenticado, mas não tem permissão para realizar esta ação. Causas
comuns:

- Tentativa de excluir o mind de outro usuário
- Tentativa de verificar uma memória com Mind Key (requer JWT)
- Mind desativado

**Correção:** Verifique se você está usando o tipo correto de token para este
endpoint.

### 404 Not Found

O caminho ou recurso solicitado não existe.

> [!CRITICAL]
> **NÃO tente adivinhar caminhos de endpoint.** Apenas os caminhos listados em
> `GET /endpoints` existem. Se você recebeu um 404, usou um caminho errado.

```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Route GET /memory/list not found",
  "docs": "https://synapse.schaefer.zone/docs/api/errors"
}
```

**Correção:** Chame `GET /endpoints` para ver a lista de endpoints válidos.
Compare sua URL com a lista caractere por caractere.

### 409 Conflict

A requisição conflita com o estado existente. Causas comuns:

- Tentativa de registrar com um email que já existe
- URL de webhook duplicada

**Correção:** Use um valor diferente, ou use `PUT` para atualizar o recurso
existente.

### 429 Too Many Requests

Você atingiu um limite de taxa. Aplica-se apenas à auth via parâmetro de
consulta `?key=` (60/min).

```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Use Authorization header for unlimited access."
}
```

Cabeçalhos da resposta:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 42
```

**Correção:** Mude para o cabeçalho `Authorization: Bearer` (sem limite de
taxa), ou aguarde `Retry-After` segundos.

### 500 Internal Server Error

Erro de servidor. Isso não deveria acontecer — se acontecer, é um bug.

**Correção:**

1. Faça retry com backoff exponencial (1s, 2s, 4s, 8s)
2. Verifique `GET /health` para ver se o servidor está no ar
3. Se persistir, relate o erro

### 503 Service Unavailable

Servidor temporariamente indisponível (ex.: durante deploy, migração de banco).

**Correção:** Aguarde e tente novamente. Verifique `GET /health`.

## Padrões de recuperação

### Retry com backoff exponencial

```python
import time
import requests

def call_with_retry(url, max_retries=3):
    for attempt in range(max_retries):
        try:
            r = requests.get(url, headers={"Authorization": f"Bearer {KEY}"})
            if r.status_code == 429:
                wait = int(r.headers.get("Retry-After", 60))
                time.sleep(wait)
                continue
            if r.status_code >= 500:
                time.sleep(2 ** attempt)
                continue
            return r
        except requests.RequestException:
            time.sleep(2 ** attempt)
    raise Exception(f"Failed after {max_retries} retries")
```

### Tratamento de erro de auth

```python
def safe_call(url, key):
    r = requests.get(url, headers={"Authorization": f"Bearer {key}"})
    if r.status_code == 401:
        # Mind Key invalid — alert user
        raise AuthError("Mind Key invalid or expired")
    return r
```

## Cenários comuns de erro

### "Mind Key fehlt oder ungültig"

- Você esqueceu o cabeçalho `Authorization`
- Você usou `?key=` mas a chave está errada
- Você está usando um JWT onde uma Mind Key é necessária

### "Route not found"

- Você tentou adivinhar um caminho que não existe
- Você usou um verbo errado (ex.: `GET /memory` vs `POST /memory`)
- Confira `GET /endpoints` para caminhos válidos

### "Rate limit exceeded"

- Você está usando `?key=` e excedeu 60 req/min
- Mude para o cabeçalho `Authorization: Bearer`

## Próximos passos

- [Autenticação](/docs/getting-started/authentication)
- [Visão geral da API](/docs/api/overview)
- [Limites de taxa](/docs/api/rate-limits)