{"title":"Errors & Fehlerbehandlung","slug":"errors","category":"api","summary":"HTTP-Statuscodes, Fehler-Antwortformat und Wiederherstellung nach häufigen Fehlern.","audience":["human","llm"],"tags":["api","errors","troubleshooting","http"],"difficulty":"beginner","updated":"2026-06-27","word_count":481,"read_minutes":2,"llm_context":"Error format: { statusCode, error, message, docs? }\nCommon errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)\n401 → check Mind Key/JWT, see /docs/getting-started/authentication\n404 → wrong path, GET /endpoints for valid list, do NOT guess paths\n429 → rate limited (?key= is 60/min), use Bearer header instead\n500 → server error, retry with backoff, check /health\ndocs field in error response links to relevant documentation.\n","lang":"de","translated":true,"requested_lang":"de","content_markdown":"\n# Errors & Fehlerbehandlung\n\nSynapse verwendet Standard-HTTP-Statuscodes mit einem konsistenten Fehler-\nAntwortformat. Diese Seite erklärt, wie du Fehler interpretierst und behebst.\n\n## Fehler-Antwortformat\n\nAlle Fehler liefern JSON mit dieser Struktur:\n\n```json\n{\n \"statusCode\": 401,\n \"error\": \"Unauthorized\",\n \"message\": \"Mind Key fehlt oder ungültig.\",\n \"docs\": \"https://synapse.schaefer.zone/docs/getting-started/authentication\"\n}\n```\n\n| Feld | Beschreibung |\n|-------|--------------|\n| `statusCode` | HTTP-Statuscode |\n| `error` | HTTP-Statusname |\n| `message` | Lesbare Fehlerbeschreibung |\n| `docs` | URL zur relevanten Doku (falls verfügbar) |\n\n## HTTP-Statuscodes\n\n### 200 OK\n\nErfolg. Die Anfrage wurde korrekt verarbeitet.\n\n### 201 Created\n\nErfolg. Eine neue Ressource wurde erstellt (z. B. `POST /memory`).\n\n### 204 No Content\n\nErfolg. Kein Body zurückgegeben (z. B. `DELETE /memory/:id`).\n\n### 400 Bad Request\n\nDie Anfrage war fehlerhaft. Häufige Ursachen:\n\n- Fehlende Pflicht-JSON-Felder\n- Ungültige JSON-Syntax\n- Ungültiger Enum-Wert (z. B. falsche Kategorie)\n\n```json\n{\n \"statusCode\": 400,\n \"error\": \"Bad Request\",\n \"message\": \"category must be one of: identity, preference, fact, project, skill, mistake, context, note, credentials\"\n}\n```\n\n**Lösung:** Prüfe den Request-Body gegen die API-Doku. Stelle sicher, dass alle\nPflichtfelder vorhanden sind und gültige Werte haben.\n\n### 401 Unauthorized\n\nAuthentifizierung fehlgeschlagen. Häufige Ursachen:\n\n- Fehlender `Authorization`-Header\n- Ungültiger Mind Key oder JWT\n- Mind Key verwendet, wo JWT erforderlich ist (oder umgekehrt)\n\n```json\n{\n \"statusCode\": 401,\n \"error\": \"Unauthorized\",\n \"message\": \"Mind Key fehlt oder ungültig.\",\n \"docs\": \"https://synapse.schaefer.zone/docs/getting-started/authentication\"\n}\n```\n\n**Lösung:** Überprüfe deinen Token. Siehe [Authentifizierung](/docs/getting-started/authentication).\n\n### 403 Forbidden\n\nDu bist authentifiziert, darfst diese Aktion aber nicht ausführen. Häufige\nUrsachen:\n\n- Versuch, den Mind eines anderen Nutzers zu löschen\n- Versuch, einen Memory mit Mind Key zu verifizieren (erfordert JWT)\n- Mind ist deaktiviert\n\n**Lösung:** Prüfe, ob du den richtigen Token-Typ für diesen Endpunkt verwendest.\n\n### 404 Not Found\n\nDer angeforderte Pfad oder die Ressource existiert nicht.\n\n> [!CRITICAL]\n> **Rate keine Endpunkt-Pfade.** Nur die in `GET /endpoints` gelisteten Pfade\n> existieren. Bei einer 404 hast du einen falschen Pfad verwendet.\n\n```json\n{\n \"statusCode\": 404,\n \"error\": \"Not Found\",\n \"message\": \"Route GET /memory/list not found\",\n \"docs\": \"https://synapse.schaefer.zone/docs/api/errors\"\n}\n```\n\n**Lösung:** Rufe `GET /endpoints` auf, um die Liste gültiger Endpunkte zu\nsehen. Vergleiche deine URL Zeichen für Zeichen mit der Liste.\n\n### 409 Conflict\n\nDie Anfrage kollidiert mit dem bestehenden Zustand. Häufige Ursachen:\n\n- Registrierung mit einer E-Mail, die bereits existiert\n- Doppelte Webhook-URL\n\n**Lösung:** Verwende einen anderen Wert oder nutze `PUT`, um die bestehende\nRessource zu aktualisieren.\n\n### 429 Too Many Requests\n\nDu hast ein Rate Limit erreicht. Betrifft nur `?key=`-Query-Parameter-Auth\n(60/min).\n\n```json\n{\n \"statusCode\": 429,\n \"error\": \"Too Many Requests\",\n \"message\": \"Rate limit exceeded. Use Authorization header for unlimited access.\"\n}\n```\n\nResponse-Header:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42\n```\n\n**Lösung:** Wechsle zum `Authorization: Bearer`-Header (kein Rate Limit) oder\nwarte `Retry-After` Sekunden.\n\n### 500 Internal Server Error\n\nServerfehler. Sollte nicht passieren — falls doch, ist es ein Bug.\n\n**Lösung:**\n\n1. Mit exponentiellem Backoff retry (1s, 2s, 4s, 8s)\n2. `GET /health` prüfen, ob der Server läuft\n3. Bei anhaltendem Fehler diesen melden\n\n### 503 Service Unavailable\n\nServer ist vorübergehend nicht verfügbar (z. B. während Deploy, DB-Migration).\n\n**Lösung:** Warten und retry. Prüfe `GET /health`.\n\n## Recovery-Patterns\n\n### Retry mit exponentiellem Backoff\n\n```python\nimport time\nimport requests\n\ndef call_with_retry(url, max_retries=3):\n for attempt in range(max_retries):\n try:\n r = requests.get(url, headers={\"Authorization\": f\"Bearer {KEY}\"})\n if r.status_code == 429:\n wait = int(r.headers.get(\"Retry-After\", 60))\n time.sleep(wait)\n continue\n if r.status_code >= 500:\n time.sleep(2 ** attempt)\n continue\n return r\n except requests.RequestException:\n time.sleep(2 ** attempt)\n raise Exception(f\"Failed after {max_retries} retries\")\n```\n\n### Auth-Fehlerbehandlung\n\n```python\ndef safe_call(url, key):\n r = requests.get(url, headers={\"Authorization\": f\"Bearer {key}\"})\n if r.status_code == 401:\n # Mind Key invalid — alert user\n raise AuthError(\"Mind Key invalid or expired\")\n return r\n```\n\n## Häufige Fehler-Szenarien\n\n### „Mind Key fehlt oder ungültig\"\n\n- Du hast den `Authorization`-Header vergessen\n- Du hast `?key=` verwendet, aber der Key ist falsch\n- Du verwendest einen JWT, wo ein Mind Key erforderlich ist\n\n### „Route not found\"\n\n- Du hast einen Pfad geraten, der nicht existiert\n- Du hast ein Verb falsch verwendet (z. B. `GET /memory` vs `POST /memory`)\n- Prüfe `GET /endpoints` für gültige Pfade\n\n### „Rate limit exceeded\"\n\n- Du verwendest `?key=` und hast 60 req/min überschritten\n- Wechsle zum `Authorization: Bearer`-Header\n\n## Nächste Schritte\n\n- [Authentifizierung](/docs/getting-started/authentication)\n- [API-Übersicht](/docs/api/overview)\n- [Rate Limits](/docs/api/rate-limits)\n","content_html":"

Errors & Fehlerbehandlung

\n

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

\n

Fehler-Antwortformat

\n

Alle Fehler liefern JSON mit dieser Struktur:

\n
{\n  "statusCode": 401,\n  "error": "Unauthorized",\n  "message": "Mind Key fehlt oder ungültig.",\n  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"\n}
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FeldBeschreibung
statusCodeHTTP-Statuscode
errorHTTP-Statusname
messageLesbare Fehlerbeschreibung
docsURL zur relevanten Doku (falls verfügbar)
\n

HTTP-Statuscodes

\n

200 OK

\n

Erfolg. Die Anfrage wurde korrekt verarbeitet.

\n

201 Created

\n

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

\n

204 No Content

\n

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

\n

400 Bad Request

\n

Die Anfrage war fehlerhaft. Häufige Ursachen:

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

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

\n

401 Unauthorized

\n

Authentifizierung fehlgeschlagen. Häufige Ursachen:

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

Lösung: Überprüfe deinen Token. Siehe Authentifizierung.

\n

403 Forbidden

\n

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

\n\n

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

\n

404 Not Found

\n

Der angeforderte Pfad oder die Ressource existiert nicht.

\n
**Rate keine Endpunkt-Pfade.** Nur die in `GET /endpoints` gelisteten Pfade\nexistieren. Bei einer 404 hast du einen falschen Pfad verwendet.
{\n  "statusCode": 404,\n  "error": "Not Found",\n  "message": "Route GET /memory/list not found",\n  "docs": "https://synapse.schaefer.zone/docs/api/errors"\n}

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

\n

409 Conflict

\n

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

\n\n

Lösung: Verwende einen anderen Wert oder nutze PUT, um die bestehende\nRessource zu aktualisieren.

\n

429 Too Many Requests

\n

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

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

Response-Header:

\n
X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42

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

\n

500 Internal Server Error

\n

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

\n

Lösung:

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

503 Service Unavailable

\n

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

\n

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

\n

Recovery-Patterns

\n

Retry mit exponentiellem Backoff

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

Auth-Fehlerbehandlung

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

Häufige Fehler-Szenarien

\n

„Mind Key fehlt oder ungültig"

\n\n

„Route not found"

\n\n

„Rate limit exceeded"

\n\n

Nächste Schritte

\n\n","urls":{"html":"/docs/api/errors","text":"/docs/api/errors?format=text","json":"/docs/api/errors?format=json","llm":"/docs/api/errors?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}