{"title":"Fouten & Foutafhandeling","slug":"errors","category":"api","summary":"HTTP-statuscodes, foutresponsformaat en hoe u veelvoorkomende fouten kunt herstellen.","audience":["human","llm"],"tags":["api","errors","troubleshooting","http"],"difficulty":"beginner","updated":"2026-06-27","word_count":510,"read_minutes":3,"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":"nl","translated":true,"requested_lang":"nl","content_markdown":"\n# Fouten & Foutafhandeling\n\nSynapse gebruikt standaard HTTP-statuscodes met een consistent foutresponsformaat.\nDeze pagina legt uit hoe u fouten kunt interpreteren en ervan kunt herstellen.\n\n## Formaat van foutrespons\n\nAlle fouten retourneren JSON met deze structuur:\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| Veld | Beschrijving |\n|------|--------------|\n| `statusCode` | HTTP-statuscode |\n| `error` | HTTP-statusnaam |\n| `message` | Door mensen leesbare foutbeschrijving |\n| `docs` | URL naar relevante documentatie (indien van toepassing) |\n\n## HTTP-statuscodes\n\n### 200 OK\n\nSucces. Het verzoek is correct verwerkt.\n\n### 201 Created\n\nSucces. Een nieuwe resource is aangemaakt (bijv. `POST /memory`).\n\n### 204 No Content\n\nSucces. Geen body geretourneerd (bijv. `DELETE /memory/:id`).\n\n### 400 Bad Request\n\nHet verzoek was ongeldig. Veelvoorkomende oorzaken:\n\n- Ontbrekende verplichte JSON-velden\n- Ongeldige JSON-syntaxis\n- Ongeldige enum-waarde (bijv. verkeerde categorie)\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**Oplossing:** Controleer de requestbody tegen de API-documentatie. Zorg dat alle\nverplichte velden aanwezig zijn en geldige waarden hebben.\n\n### 401 Unauthorized\n\nAuthenticatie mislukt. Veelvoorkomende oorzaken:\n\n- Ontbrekende `Authorization`-header\n- Ongeldige Mind Key of JWT\n- Een Mind Key gebruiken waar een JWT vereist is (of omgekeerd)\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**Oplossing:** Verifieer uw token. Zie [Authenticatie](/docs/getting-started/authentication).\n\n### 403 Forbidden\n\nU bent geauthenticeerd maar mag deze actie niet uitvoeren. Veelvoorkomende oorzaken:\n\n- Poging om een mind van een andere gebruiker te verwijderen\n- Poging om een memory te verifiëren met een Mind Key (vereist JWT)\n- Mind is uitgeschakeld\n\n**Oplossing:** Controleer of u het juiste tokentype gebruikt voor dit eindpunt.\n\n### 404 Not Found\n\nHet aangevraagde pad of de resource bestaat niet.\n\n> [!CRITICAL]\n> **Raad GEEN eindpuntpaden.** Alleen de paden vermeld in `GET /endpoints`\n> bestaan. Als u een 404 krijgt, heeft u een verkeerd pad gebruikt.\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**Oplossing:** Roep `GET /endpoints` aan om de lijst met geldige eindpunten te zien.\nVergelijk uw URL teken voor teken met de lijst.\n\n### 409 Conflict\n\nHet verzoek conflicteert met de bestaande staat. Veelvoorkomende oorzaken:\n\n- Poging om te registreren met een e-mailadres dat al bestaat\n- Dubbele webhook-URL\n\n**Oplossing:** Gebruik een andere waarde, of gebruik `PUT` om de bestaande resource bij te werken.\n\n### 429 Too Many Requests\n\nU heeft een ratelimit bereikt. Geldt alleen voor `?key=`-queryparameter-authenticatie (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\nResponsheaders:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42\n```\n\n**Oplossing:** Schakel over naar `Authorization: Bearer`-header (geen ratelimit), of wacht\n`Retry-After` seconden.\n\n### 500 Internal Server Error\n\nServerfout. Dit zou niet moeten gebeuren — als het toch voorkomt, is het een bug.\n\n**Oplossing:**\n\n1. Probeer opnieuw met exponentiële backoff (1s, 2s, 4s, 8s)\n2. Controleer `GET /health` om te zien of de server draait\n3. Als het aanhoudt, meld de fout\n\n### 503 Service Unavailable\n\nDe server is tijdelijk niet beschikbaar (bijv. tijdens deployment, databasemigratie).\n\n**Oplossing:** Wacht en probeer opnieuw. Controleer `GET /health`.\n\n## Herstelpatronen\n\n### Opnieuw proberen met exponentiële 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-foutafhandeling\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## Veelvoorkomende foutscenario's\n\n### \"Mind Key fehlt oder ungültig\"\n\n- U bent de `Authorization`-header vergeten\n- U heeft `?key=` gebruikt maar de sleutel is onjuist\n- U gebruikt een JWT waar een Mind Key vereist is\n\n### \"Route not found\"\n\n- U heeft een pad geraden dat niet bestaat\n- U heeft een werkwoord verkeerd gebruikt (bijv. `GET /memory` vs `POST /memory`)\n- Controleer `GET /endpoints` voor geldige paden\n\n### \"Rate limit exceeded\"\n\n- U gebruikt `?key=` en heeft 60 aanvragen/min overschreden\n- Schakel over naar `Authorization: Bearer`-header\n\n## Volgende stappen\n\n- [Authenticatie](/docs/getting-started/authentication)\n- [API-overzicht](/docs/api/overview)\n- [Ratelimits](/docs/api/rate-limits)\n","content_html":"

Fouten & Foutafhandeling

\n

Synapse gebruikt standaard HTTP-statuscodes met een consistent foutresponsformaat.\nDeze pagina legt uit hoe u fouten kunt interpreteren en ervan kunt herstellen.

\n

Formaat van foutrespons

\n

Alle fouten retourneren JSON met deze structuur:

\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
VeldBeschrijving
statusCodeHTTP-statuscode
errorHTTP-statusnaam
messageDoor mensen leesbare foutbeschrijving
docsURL naar relevante documentatie (indien van toepassing)
\n

HTTP-statuscodes

\n

200 OK

\n

Succes. Het verzoek is correct verwerkt.

\n

201 Created

\n

Succes. Een nieuwe resource is aangemaakt (bijv. POST /memory).

\n

204 No Content

\n

Succes. Geen body geretourneerd (bijv. DELETE /memory/:id).

\n

400 Bad Request

\n

Het verzoek was ongeldig. Veelvoorkomende oorzaken:

\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}

Oplossing: Controleer de requestbody tegen de API-documentatie. Zorg dat alle\nverplichte velden aanwezig zijn en geldige waarden hebben.

\n

401 Unauthorized

\n

Authenticatie mislukt. Veelvoorkomende oorzaken:

\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}

Oplossing: Verifieer uw token. Zie Authenticatie.

\n

403 Forbidden

\n

U bent geauthenticeerd maar mag deze actie niet uitvoeren. Veelvoorkomende oorzaken:

\n\n

Oplossing: Controleer of u het juiste tokentype gebruikt voor dit eindpunt.

\n

404 Not Found

\n

Het aangevraagde pad of de resource bestaat niet.

\n
**Raad GEEN eindpuntpaden.** Alleen de paden vermeld in `GET /endpoints`\nbestaan. Als u een 404 krijgt, heeft u een verkeerd pad gebruikt.
{\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}

Oplossing: Roep GET /endpoints aan om de lijst met geldige eindpunten te zien.\nVergelijk uw URL teken voor teken met de lijst.

\n

409 Conflict

\n

Het verzoek conflicteert met de bestaande staat. Veelvoorkomende oorzaken:

\n\n

Oplossing: Gebruik een andere waarde, of gebruik PUT om de bestaande resource bij te werken.

\n

429 Too Many Requests

\n

U heeft een ratelimit bereikt. Geldt alleen voor ?key=-queryparameter-authenticatie (60/min).

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

Responsheaders:

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

Oplossing: Schakel over naar Authorization: Bearer-header (geen ratelimit), of wacht\nRetry-After seconden.

\n

500 Internal Server Error

\n

Serverfout. Dit zou niet moeten gebeuren — als het toch voorkomt, is het een bug.

\n

Oplossing:

\n
    \n
  1. Probeer opnieuw met exponentiële backoff (1s, 2s, 4s, 8s)
    2. \n
  2. Controleer GET /health om te zien of de server draait
    3. \n
  3. Als het aanhoudt, meld de fout
    4. \n
\n

503 Service Unavailable

\n

De server is tijdelijk niet beschikbaar (bijv. tijdens deployment, databasemigratie).

\n

Oplossing: Wacht en probeer opnieuw. Controleer GET /health.

\n

Herstelpatronen

\n

Opnieuw proberen met exponentiële 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-foutafhandeling

\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

Veelvoorkomende foutscenario's

\n

"Mind Key fehlt oder ungültig"

\n\n

"Route not found"

\n\n

"Rate limit exceeded"

\n\n

Volgende stappen

\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"]}