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:

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

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)

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

{
  "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.

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.

{
  "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).

{
  "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

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

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
• API-Übersicht
• Rate Limits