# Errors & Fehlerbehandlung
SUMMARY: HTTP-Statuscodes, Fehler-Antwortformat und Wiederherstellung nach häufigen Fehlern.

KEY CONTEXT:
Error format: { statusCode, error, message, docs? }
Common errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)
401 → check Mind Key/JWT, see /docs/getting-started/authentication
404 → wrong path, GET /endpoints for valid list, do NOT guess paths
429 → rate limited (?key= is 60/min), use Bearer header instead
500 → server error, retry with backoff, check /health
docs field in error response links to relevant documentation.

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:
[CODE BLOCK]
| Feld | Beschreibung |
|-------|--------------|
|  | HTTP-Statuscode |
|  | HTTP-Statusname |
|  | Lesbare Fehlerbeschreibung |
|  | 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. ).
204 No Content
Erfolg. Kein Body zurückgegeben (z. B. ).
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)
[CODE BLOCK]
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 -Header
- Ungültiger Mind Key oder JWT
- Mind Key verwendet, wo JWT erforderlich ist (oder umgekehrt)
[CODE BLOCK]
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.
> [!CRITICAL]
> Rate keine Endpunkt-Pfade. Nur die in  gelisteten Pfade
> existieren. Bei einer 404 hast du einen falschen Pfad verwendet.
[CODE BLOCK]
Lösung: Rufe  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 , um die bestehende
Ressource zu aktualisieren.
429 Too Many Requests
Du hast ein Rate Limit erreicht. Betrifft nur -Query-Parameter-Auth
(60/min).
[CODE BLOCK]
Response-Header:
[CODE BLOCK]
Lösung: Wechsle zum -Header (kein Rate Limit) oder
warte  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.  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 .
Recovery-Patterns
Retry mit exponentiellem Backoff
[CODE BLOCK]
Auth-Fehlerbehandlung
[CODE BLOCK]
Häufige Fehler-Szenarien
„Mind Key fehlt oder ungültig"
- Du hast den -Header vergessen
- Du hast  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.  vs )
- Prüfe  für gültige Pfade
„Rate limit exceeded"
- Du verwendest  und hast 60 req/min überschritten
- Wechsle zum -Header
Nächste Schritte
- Authentifizierung
- API-Übersicht
- Rate Limits