# 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:

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

| Veld | Beschrijving |
|------|--------------|
| `statusCode` | HTTP-statuscode |
| `error` | HTTP-statusnaam |
| `message` | Door mensen leesbare foutbeschrijving |
| `docs` | URL naar relevante documentatie (indien van toepassing) |

## 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)

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

```json
{
  "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](/docs/getting-started/authentication).

### 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.

> [!CRITICAL]
> **Raad GEEN eindpuntpaden.** Alleen de paden vermeld in `GET /endpoints`
> bestaan. Als u een 404 krijgt, heeft u een verkeerd pad gebruikt.

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

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

```python
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

```python
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](/docs/getting-started/authentication)
- [API-overzicht](/docs/api/overview)
- [Ratelimits](/docs/api/rate-limits)