# Errors & Fehlerbehandlung

Synapse verwendet Standard-HTTP-Statuscodes mit einem konsistenten Fehler-
Antwortformat. Diese Seite erklärt, wie du Fehler interpretierst und behebst.

## Fehler-Antwortformat

Alle Fehler liefern JSON mit dieser Struktur:

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

| Feld | Beschreibung |
|-------|--------------|
| `statusCode` | HTTP-Statuscode |
| `error` | HTTP-Statusname |
| `message` | Lesbare Fehlerbeschreibung |
| `docs` | URL zur relevanten Doku (falls verfügbar) |

## HTTP-Statuscodes

### 200 OK

Erfolg. Die Anfrage wurde korrekt verarbeitet.

### 201 Created

Erfolg. Eine neue Ressource wurde erstellt (z. B. `POST /memory`).

### 204 No Content

Erfolg. Kein Body zurückgegeben (z. B. `DELETE /memory/:id`).

### 400 Bad Request

Die Anfrage war fehlerhaft. Häufige Ursachen:

- Fehlende Pflicht-JSON-Felder
- Ungültige JSON-Syntax
- Ungültiger Enum-Wert (z. B. falsche Kategorie)

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

**Lösung:** Prüfe den Request-Body gegen die API-Doku. Stelle sicher, dass alle
Pflichtfelder vorhanden sind und gültige Werte haben.

### 401 Unauthorized

Authentifizierung fehlgeschlagen. Häufige Ursachen:

- Fehlender `Authorization`-Header
- Ungültiger Mind Key oder JWT
- Mind Key verwendet, wo JWT erforderlich ist (oder umgekehrt)

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

**Lösung:** Überprüfe deinen Token. Siehe [Authentifizierung](/docs/getting-started/authentication).

### 403 Forbidden

Du bist authentifiziert, darfst diese Aktion aber nicht ausführen. Häufige
Ursachen:

- Versuch, den Mind eines anderen Nutzers zu löschen
- Versuch, einen Memory mit Mind Key zu verifizieren (erfordert JWT)
- Mind ist deaktiviert

**Lösung:** Prüfe, ob du den richtigen Token-Typ für diesen Endpunkt verwendest.

### 404 Not Found

Der angeforderte Pfad oder die Ressource existiert nicht.

> [!CRITICAL]
> **Rate keine Endpunkt-Pfade.** Nur die in `GET /endpoints` gelisteten Pfade
> existieren. Bei einer 404 hast du einen falschen Pfad verwendet.

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

**Lösung:** Rufe `GET /endpoints` auf, um die Liste gültiger Endpunkte zu
sehen. Vergleiche deine URL Zeichen für Zeichen mit der Liste.

### 409 Conflict

Die Anfrage kollidiert mit dem bestehenden Zustand. Häufige Ursachen:

- Registrierung mit einer E-Mail, die bereits existiert
- Doppelte Webhook-URL

**Lösung:** Verwende einen anderen Wert oder nutze `PUT`, um die bestehende
Ressource zu aktualisieren.

### 429 Too Many Requests

Du hast ein Rate Limit erreicht. Betrifft nur `?key=`-Query-Parameter-Auth
(60/min).

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

Response-Header:

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

**Lösung:** Wechsle zum `Authorization: Bearer`-Header (kein Rate Limit) oder
warte `Retry-After` Sekunden.

### 500 Internal Server Error

Serverfehler. Sollte nicht passieren — falls doch, ist es ein Bug.

**Lösung:**

1. Mit exponentiellem Backoff retry (1s, 2s, 4s, 8s)
2. `GET /health` prüfen, ob der Server läuft
3. Bei anhaltendem Fehler diesen melden

### 503 Service Unavailable

Server ist vorübergehend nicht verfügbar (z. B. während Deploy, DB-Migration).

**Lösung:** Warten und retry. Prüfe `GET /health`.

## Recovery-Patterns

### Retry mit exponentiellem Backoff

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

### Auth-Fehlerbehandlung

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

## Häufige Fehler-Szenarien

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

- Du hast den `Authorization`-Header vergessen
- Du hast `?key=` verwendet, aber der Key ist falsch
- Du verwendest einen JWT, wo ein Mind Key erforderlich ist

### „Route not found"

- Du hast einen Pfad geraten, der nicht existiert
- Du hast ein Verb falsch verwendet (z. B. `GET /memory` vs `POST /memory`)
- Prüfe `GET /endpoints` für gültige Pfade

### „Rate limit exceeded"

- Du verwendest `?key=` und hast 60 req/min überschritten
- Wechsle zum `Authorization: Bearer`-Header

## Nächste Schritte

- [Authentifizierung](/docs/getting-started/authentication)
- [API-Übersicht](/docs/api/overview)
- [Rate Limits](/docs/api/rate-limits)