# Errori e gestione degli errori

Synapse utilizza codici di stato HTTP standard con un formato di risposta di
errore coerente. Questa pagina spiega come interpretare gli errori e come
riprendersi.

## Formato della risposta di errore

Tutti gli errori restituiscono JSON con questa struttura:

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

| Campo | Descrizione |
|-------|-------------|
| `statusCode` | Codice di stato HTTP |
| `error` | Nome dello stato HTTP |
| `message` | Descrizione dell'errore leggibile dall'umano |
| `docs` | URL alla documentazione pertinente (quando applicabile) |

## Codici di stato HTTP

### 200 OK

Successo. La richiesta è stata elaborata correttamente.

### 201 Created

Successo. Una nuova risorsa è stata creata (es. `POST /memory`).

### 204 No Content

Successo. Nessun corpo restituito (es. `DELETE /memory/:id`).

### 400 Bad Request

La richiesta era malformata. Cause comuni:

- Campi JSON obbligatori mancanti
- Sintassi JSON non valida
- Valore enum non valido (es. categoria errata)

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

**Soluzione:** Verifichi il corpo della richiesta rispetto alla documentazione
API. Si assicuri che tutti i campi obbligatori siano presenti e abbiano valori
validi.

### 401 Unauthorized

Autenticazione fallita. Cause comuni:

- Header `Authorization` mancante
- Mind Key o JWT non valido
- Uso di una Mind Key dove è richiesto un JWT (o viceversa)

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

**Soluzione:** Verifichi il suo token. Veda [Autenticazione](/docs/getting-started/authentication).

### 403 Forbidden

È autenticato ma non autorizzato a eseguire questa azione. Cause comuni:

- Tentativo di eliminare la mente di un altro utente
- Tentativo di verificare una memoria con una Mind Key (richiede JWT)
- La mente è disabilitata

**Soluzione:** Verifichi se sta usando il tipo di token corretto per questo
endpoint.

### 404 Not Found

Il percorso o la risorsa richiesta non esiste.

> [!CRITICAL]
> **Non indovini i percorsi degli endpoint.** Esistono solo i percorsi elencati
> in `GET /endpoints`. Se ottiene un 404, ha usato un percorso errato.

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

**Soluzione:** Chiami `GET /endpoints` per vedere la lista degli endpoint
validi. Confronti la sua URL con la lista carattere per carattere.

### 409 Conflict

La richiesta è in conflitto con lo stato esistente. Cause comuni:

- Tentativo di registrazione con un'email già esistente
- URL webhook duplicato

**Soluzione:** Usi un valore diverso, oppure usi `PUT` per aggiornare la
risorsa esistente.

### 429 Too Many Requests

Ha raggiunto un limite di traffico. Si applica solo all'autenticazione tramite
parametro query `?key=` (60/min).

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

Header di risposta:

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

**Soluzione:** Passi all'header `Authorization: Bearer` (nessun limite), oppure
attenda `Retry-After` secondi.

### 500 Internal Server Error

Errore del server. Non dovrebbe accadere — se accade, è un bug.

**Soluzione:**

1. Riprovi con backoff esponenziale (1s, 2s, 4s, 8s)
2. Verifichi con `GET /health` se il server è attivo
3. Se persiste, segnali l'errore

### 503 Service Unavailable

Il server è temporaneamente non disponibile (es. durante il deployment,
migrazione del database).

**Soluzione:** Attenda e riprovi. Verifichi `GET /health`.

## Modelli di recupero

### Riprova con backoff esponenziale

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

### Gestione errori di autenticazione

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

## Scenari di errore comuni

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

- Ha dimenticato l'header `Authorization`
- Ha usato `?key=` ma la chiave è errata
- Sta usando un JWT dove è richiesta una Mind Key

### "Route not found"

- Ha indovinato un percorso che non esiste
- Ha usato un verbo sbagliato (es. `GET /memory` vs `POST /memory`)
- Verifichi `GET /endpoints` per i percorsi validi

### "Rate limit exceeded"

- Sta usando `?key=` e ha superato 60 req/min
- Passi all'header `Authorization: Bearer`

## Prossimi passi

- [Autenticazione](/docs/getting-started/authentication)
- [Panoramica API](/docs/api/overview)
- [Limiti di traffico](/docs/api/rate-limits)