Fouten & Foutafhandeling

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

Formaat van foutrespons

Alle fouten retourneren JSON met deze structuur:

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

HTTP-statuscodes

200 OK

Succes. Het verzoek is correct verwerkt.

201 Created

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

204 No Content

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

400 Bad Request

Het verzoek was ongeldig. Veelvoorkomende oorzaken:

• Ontbrekende verplichte JSON-velden
• Ongeldige JSON-syntaxis
• Ongeldige enum-waarde (bijv. verkeerde categorie)

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

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

401 Unauthorized

Authenticatie mislukt. Veelvoorkomende oorzaken:

• Ontbrekende Authorization-header
• Ongeldige Mind Key of JWT
• Een Mind Key gebruiken waar een JWT vereist is (of omgekeerd)

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

Oplossing: Verifieer uw token. Zie Authenticatie.

403 Forbidden

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

• Poging om een mind van een andere gebruiker te verwijderen
• Poging om een memory te verifiëren met een Mind Key (vereist JWT)
• Mind is uitgeschakeld

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

404 Not Found

Het aangevraagde pad of de resource bestaat niet.

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

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

409 Conflict

Het verzoek conflicteert met de bestaande staat. Veelvoorkomende oorzaken:

• Poging om te registreren met een e-mailadres dat al bestaat
• Dubbele webhook-URL

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

429 Too Many Requests

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

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

Responsheaders:

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

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

500 Internal Server Error

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

Oplossing:

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

503 Service Unavailable

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

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

Herstelpatronen

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

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

Veelvoorkomende foutscenario's

"Mind Key fehlt oder ungültig"

• U bent de Authorization-header vergeten
• U heeft ?key= gebruikt maar de sleutel is onjuist
• U gebruikt een JWT waar een Mind Key vereist is

"Route not found"

• U heeft een pad geraden dat niet bestaat
• U heeft een werkwoord verkeerd gebruikt (bijv. GET /memory vs POST /memory)
• Controleer GET /endpoints voor geldige paden

"Rate limit exceeded"

• U gebruikt ?key= en heeft 60 aanvragen/min overschreden
• Schakel over naar Authorization: Bearer-header

Volgende stappen

• Authenticatie
• API-overzicht
• Ratelimits