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:

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

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)

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

{
  "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.

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.

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

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

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

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
• API-översikt
• Hastighetsgränser