{"title":"Fel & felhantering","slug":"errors","category":"api","summary":"HTTP-statuskoder, format för felsvar och hur man återhämtar sig från vanliga fel.","audience":["human","llm"],"tags":["api","errors","troubleshooting","http"],"difficulty":"beginner","updated":"2026-06-27","word_count":478,"read_minutes":2,"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":"sv","translated":true,"requested_lang":"sv","content_markdown":"\n# Fel & felhantering\n\nSynapse använder standardiserade HTTP-statuskoder med ett konsekvent felsvarsformat.\nDen här sidan förklarar hur man tolkar och återhämtar sig från fel.\n\n## Format för felsvar\n\nAlla fel returnerar JSON med denna struktur:\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| Fält | Beskrivning |\n|-------|-------------|\n| `statusCode` | HTTP-statuskod |\n| `error` | HTTP-statusnamn |\n| `message` | Läsbar felbeskrivning för människor |\n| `docs` | URL till relevant dokumentation (när tillämpligt) |\n\n## HTTP-statuskoder\n\n### 200 OK\n\nLyckades. Begäran behandlades korrekt.\n\n### 201 Created\n\nLyckades. En ny resurs skapades (t.ex. `POST /memory`).\n\n### 204 No Content\n\nLyckades. Ingen body returnerades (t.ex. `DELETE /memory/:id`).\n\n### 400 Bad Request\n\nBegäran var felaktig. Vanliga orsaker:\n\n- Saknade obligatoriska JSON-fält\n- Ogiltig JSON-syntax\n- Ogiltigt enum-värde (t.ex. fel kategori)\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**Lösning:** Kontrollera begärans body mot API-dokumentationen. Se till att alla\nobligatoriska fält finns med och har giltiga värden.\n\n### 401 Unauthorized\n\nAutentiseringen misslyckades. Vanliga orsaker:\n\n- Saknad `Authorization`-header\n- Ogiltig Mind Key eller JWT\n- Användning av en Mind Key där JWT krävs (eller tvärtom)\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**Lösning:** Verifiera din token. Se [Autentisering](/docs/getting-started/authentication).\n\n### 403 Forbidden\n\nNi är autentiserade men får inte utföra denna åtgärd. Vanliga orsaker:\n\n- Försöker ta bort en annan användares mind\n- Försöker verifiera ett minne med en Mind Key (kräver JWT)\n- Mind är inaktiverad\n\n**Lösning:** Kontrollera om ni använder rätt tokentyp för denna endpoint.\n\n### 404 Not Found\n\nDen begärda sökvägen eller resursen finns inte.\n\n> [!CRITICAL]\n> **Gissa INTE endpointsökvägar.** Endast de sökvägar som listas i\n> `GET /endpoints` existerar. Om ni får 404 använde ni en felaktig sökväg.\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**Lösning:** Anropa `GET /endpoints` för att se listan över giltiga endpoints.\nJämför er URL mot listan tecken för tecken.\n\n### 409 Conflict\n\nBegäran är i konflikt med befintligt tillstånd. Vanliga orsaker:\n\n- Försöker registrera med en e-postadress som redan finns\n- Duplicerad webhook-URL\n\n**Lösning:** Använd ett annat värde, eller använd `PUT` för att uppdatera\nbefintlig resurs.\n\n### 429 Too Many Requests\n\nNi nådde en hastighetsgräns. Gäller endast `?key=`-queryparameter-autentisering\n(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\nSvarshuvuden:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42\n```\n\n**Lösning:** Byt till `Authorization: Bearer`-header (ingen hastighetsgräns),\neller vänta `Retry-After` sekunder.\n\n### 500 Internal Server Error\n\nServerfel. Detta bör inte inträffa — om det gör det är det en bugg.\n\n**Lösning:**\n\n1. Försök igen med exponentiell backoff (1 s, 2 s, 4 s, 8 s)\n2. Kontrollera `GET /health` för att se om servern är uppe\n3. Rapportera felet om det kvarstår\n\n### 503 Service Unavailable\n\nServern är tillfälligt nere (t.ex. under driftsättning, databasmigrering).\n\n**Lösning:** Vänta och försök igen. Kontrollera `GET /health`.\n\n## Återställningsmönster\n\n### Försök igen med exponentiell 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### Hantering av autentiseringsfel\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## Vanliga felscenarier\n\n### \"Mind Key fehlt oder ungültig\"\n\n- Ni glömde `Authorization`-headern\n- Ni använde `?key=` men nyckeln är fel\n- Ni använder en JWT där en Mind Key krävs\n\n### \"Route not found\"\n\n- Ni gissade en sökväg som inte finns\n- Ni använde ett verb fel (t.ex. `GET /memory` vs `POST /memory`)\n- Kontrollera `GET /endpoints` för giltiga sökvägar\n\n### \"Rate limit exceeded\"\n\n- Ni använder `?key=` och överskred 60 req/min\n- Byt till `Authorization: Bearer`-header\n\n## Nästa steg\n\n- [Autentisering](/docs/getting-started/authentication)\n- [API-översikt](/docs/api/overview)\n- [Hastighetsgränser](/docs/api/rate-limits)\n","content_html":"

Fel & felhantering

\n

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

\n

Format för felsvar

\n

Alla fel returnerar JSON med denna struktur:

\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
FältBeskrivning
statusCodeHTTP-statuskod
errorHTTP-statusnamn
messageLäsbar felbeskrivning för människor
docsURL till relevant dokumentation (när tillämpligt)
\n

HTTP-statuskoder

\n

200 OK

\n

Lyckades. Begäran behandlades korrekt.

\n

201 Created

\n

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

\n

204 No Content

\n

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

\n

400 Bad Request

\n

Begäran var felaktig. Vanliga orsaker:

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

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

\n

401 Unauthorized

\n

Autentiseringen misslyckades. Vanliga orsaker:

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

Lösning: Verifiera din token. Se Autentisering.

\n

403 Forbidden

\n

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

\n\n

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

\n

404 Not Found

\n

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

\n
**Gissa INTE endpointsökvägar.** Endast de sökvägar som listas i\n`GET /endpoints` existerar. Om ni får 404 använde ni en felaktig sökväg.
{\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}

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

\n

409 Conflict

\n

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

\n\n

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

\n

429 Too Many Requests

\n

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

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

Svarshuvuden:

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

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

\n

500 Internal Server Error

\n

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

\n

Lösning:

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

503 Service Unavailable

\n

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

\n

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

\n

Återställningsmönster

\n

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

Hantering av autentiseringsfel

\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

Vanliga felscenarier

\n

"Mind Key fehlt oder ungültig"

\n\n

"Route not found"

\n\n

"Rate limit exceeded"

\n\n

Nästa steg

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