# Fel & felhantering

Synapse använder standardiserade HTTP-statuskoder med ett konsekvent felsvarsformat.
Den här sidan förklarar hur man tolkar och återhämtar sig från fel.

## Format för felsvar

Alla fel returnerar JSON med denna struktur:

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

| Fält | Beskrivning |
|-------|-------------|
| `statusCode` | HTTP-statuskod |
| `error` | HTTP-statusnamn |
| `message` | Läsbar felbeskrivning för människor |
| `docs` | URL till relevant dokumentation (när tillämpligt) |

## HTTP-statuskoder

### 200 OK

Lyckades. Begäran behandlades korrekt.

### 201 Created

Lyckades. En ny resurs skapades (t.ex. `POST /memory`).

### 204 No Content

Lyckades. Ingen body returnerades (t.ex. `DELETE /memory/:id`).

### 400 Bad Request

Begäran var felaktig. Vanliga orsaker:

- Saknade obligatoriska JSON-fält
- Ogiltig JSON-syntax
- Ogiltigt enum-värde (t.ex. fel kategori)

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

**Lösning:** Kontrollera begärans body mot API-dokumentationen. Se till att alla
obligatoriska fält finns med och har giltiga värden.

### 401 Unauthorized

Autentiseringen misslyckades. Vanliga orsaker:

- Saknad `Authorization`-header
- Ogiltig Mind Key eller JWT
- Användning av en Mind Key där JWT krävs (eller tvärtom)

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

**Lösning:** Verifiera din token. Se [Autentisering](/docs/getting-started/authentication).

### 403 Forbidden

Ni är autentiserade men får inte utföra denna åtgärd. Vanliga orsaker:

- Försöker ta bort en annan användares mind
- Försöker verifiera ett minne med en Mind Key (kräver JWT)
- Mind är inaktiverad

**Lösning:** Kontrollera om ni använder rätt tokentyp för denna endpoint.

### 404 Not Found

Den begärda sökvägen eller resursen finns inte.

> [!CRITICAL]
> **Gissa INTE endpointsökvägar.** Endast de sökvägar som listas i
> `GET /endpoints` existerar. Om ni får 404 använde ni en felaktig sökväg.

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

**Lösning:** Anropa `GET /endpoints` för att se listan över giltiga endpoints.
Jämför er URL mot listan tecken för tecken.

### 409 Conflict

Begäran är i konflikt med befintligt tillstånd. Vanliga orsaker:

- Försöker registrera med en e-postadress som redan finns
- Duplicerad webhook-URL

**Lösning:** Använd ett annat värde, eller använd `PUT` för att uppdatera
befintlig resurs.

### 429 Too Many Requests

Ni nådde en hastighetsgräns. Gäller endast `?key=`-queryparameter-autentisering
(60/min).

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

Svarshuvuden:

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

**Lösning:** Byt till `Authorization: Bearer`-header (ingen hastighetsgräns),
eller vänta `Retry-After` sekunder.

### 500 Internal Server Error

Serverfel. Detta bör inte inträffa — om det gör det är det en bugg.

**Lösning:**

1. Försök igen med exponentiell backoff (1 s, 2 s, 4 s, 8 s)
2. Kontrollera `GET /health` för att se om servern är uppe
3. Rapportera felet om det kvarstår

### 503 Service Unavailable

Servern är tillfälligt nere (t.ex. under driftsättning, databasmigrering).

**Lösning:** Vänta och försök igen. Kontrollera `GET /health`.

## Återställningsmönster

### Försök igen med exponentiell 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")
```

### Hantering av autentiseringsfel

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

## Vanliga felscenarier

### "Mind Key fehlt oder ungültig"

- Ni glömde `Authorization`-headern
- Ni använde `?key=` men nyckeln är fel
- Ni använder en JWT där en Mind Key krävs

### "Route not found"

- Ni gissade en sökväg som inte finns
- Ni använde ett verb fel (t.ex. `GET /memory` vs `POST /memory`)
- Kontrollera `GET /endpoints` för giltiga sökvägar

### "Rate limit exceeded"

- Ni använder `?key=` och överskred 60 req/min
- Byt till `Authorization: Bearer`-header

## Nästa steg

- [Autentisering](/docs/getting-started/authentication)
- [API-översikt](/docs/api/overview)
- [Hastighetsgränser](/docs/api/rate-limits)