{"title":"Errors & Error Handling","slug":"errors","category":"api","summary":"HTTP status codes, error response format, and how to recover from common errors.","audience":["human","llm"],"tags":["api","errors","troubleshooting","http"],"difficulty":"beginner","updated":"2026-06-27","word_count":505,"read_minutes":3,"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":"en","translated":true,"requested_lang":"en","content_markdown":"\n# Errors & Error Handling\n\nSynapse uses standard HTTP status codes with a consistent error response format.\nThis page explains how to interpret and recover from errors.\n\n## Error Response Format\n\nAll errors return JSON with this structure:\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| Field | Description |\n|-------|-------------|\n| `statusCode` | HTTP status code |\n| `error` | HTTP status name |\n| `message` | Human-readable error description |\n| `docs` | URL to relevant documentation (when applicable) |\n\n## HTTP Status Codes\n\n### 200 OK\n\nSuccess. The request was processed correctly.\n\n### 201 Created\n\nSuccess. A new resource was created (e.g. `POST /memory`).\n\n### 204 No Content\n\nSuccess. No body returned (e.g. `DELETE /memory/:id`).\n\n### 400 Bad Request\n\nThe request was malformed. Common causes:\n\n- Missing required JSON fields\n- Invalid JSON syntax\n- Invalid enum value (e.g. wrong category)\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**Fix:** Check the request body against the API docs. Ensure all required\nfields are present and have valid values.\n\n### 401 Unauthorized\n\nAuthentication failed. Common causes:\n\n- Missing `Authorization` header\n- Invalid Mind Key or JWT\n- Using a Mind Key where a JWT is required (or vice versa)\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**Fix:** Verify your token. See [Authentication](/docs/getting-started/authentication).\n\n### 403 Forbidden\n\nYou're authenticated but not allowed to perform this action. Common causes:\n\n- Trying to delete another user's mind\n- Trying to verify a memory with a Mind Key (requires JWT)\n- Mind is disabled\n\n**Fix:** Check if you're using the correct token type for this endpoint.\n\n### 404 Not Found\n\nThe requested path or resource doesn't exist.\n\n> [!CRITICAL]\n> **Do NOT guess endpoint paths.** Only the paths listed in `GET /endpoints`\n> exist. If you get a 404, you used a wrong path.\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**Fix:** Call `GET /endpoints` to see the list of valid endpoints. Compare\nyour URL against the list character-by-character.\n\n### 409 Conflict\n\nThe request conflicts with existing state. Common causes:\n\n- Trying to register with an email that already exists\n- Duplicate webhook URL\n\n**Fix:** Use a different value, or use `PUT` to update the existing resource.\n\n### 429 Too Many Requests\n\nYou hit a rate limit. Only applies to `?key=` query parameter auth (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\nResponse headers:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42\n```\n\n**Fix:** Switch to `Authorization: Bearer` header (no rate limit), or wait\n`Retry-After` seconds.\n\n### 500 Internal Server Error\n\nServer error. This shouldn't happen — if it does, it's a bug.\n\n**Fix:**\n\n1. Retry with exponential backoff (1s, 2s, 4s, 8s)\n2. Check `GET /health` to see if the server is up\n3. If persistent, report the error\n\n### 503 Service Unavailable\n\nServer is temporarily down (e.g. during deployment, database migration).\n\n**Fix:** Wait and retry. Check `GET /health`.\n\n## Recovery Patterns\n\n### Retry with exponential 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### Auth error handling\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## Common Error Scenarios\n\n### \"Mind Key fehlt oder ungültig\"\n\n- You forgot the `Authorization` header\n- You used `?key=` but the key is wrong\n- You're using a JWT where a Mind Key is required\n\n### \"Route not found\"\n\n- You guessed a path that doesn't exist\n- You used a verb wrong (e.g. `GET /memory` vs `POST /memory`)\n- Check `GET /endpoints` for valid paths\n\n### \"Rate limit exceeded\"\n\n- You're using `?key=` and exceeded 60 req/min\n- Switch to `Authorization: Bearer` header\n\n## Next Steps\n\n- [Authentication](/docs/getting-started/authentication)\n- [API Overview](/docs/api/overview)\n- [Rate Limits](/docs/api/rate-limits)\n","content_html":"

Errors & Error Handling

\n

Synapse uses standard HTTP status codes with a consistent error response format.\nThis page explains how to interpret and recover from errors.

\n

Error Response Format

\n

All errors return JSON with this structure:

\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
FieldDescription
statusCodeHTTP status code
errorHTTP status name
messageHuman-readable error description
docsURL to relevant documentation (when applicable)
\n

HTTP Status Codes

\n

200 OK

\n

Success. The request was processed correctly.

\n

201 Created

\n

Success. A new resource was created (e.g. POST /memory).

\n

204 No Content

\n

Success. No body returned (e.g. DELETE /memory/:id).

\n

400 Bad Request

\n

The request was malformed. Common causes:

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

Fix: Check the request body against the API docs. Ensure all required\nfields are present and have valid values.

\n

401 Unauthorized

\n

Authentication failed. Common causes:

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

Fix: Verify your token. See Authentication.

\n

403 Forbidden

\n

You're authenticated but not allowed to perform this action. Common causes:

\n\n

Fix: Check if you're using the correct token type for this endpoint.

\n

404 Not Found

\n

The requested path or resource doesn't exist.

\n
**Do NOT guess endpoint paths.** Only the paths listed in `GET /endpoints`\nexist. If you get a 404, you used a wrong path.
{\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}

Fix: Call GET /endpoints to see the list of valid endpoints. Compare\nyour URL against the list character-by-character.

\n

409 Conflict

\n

The request conflicts with existing state. Common causes:

\n\n

Fix: Use a different value, or use PUT to update the existing resource.

\n

429 Too Many Requests

\n

You hit a rate limit. Only applies to ?key= query parameter auth (60/min).

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

Response headers:

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

Fix: Switch to Authorization: Bearer header (no rate limit), or wait\nRetry-After seconds.

\n

500 Internal Server Error

\n

Server error. This shouldn't happen — if it does, it's a bug.

\n

Fix:

\n
    \n
  1. Retry with exponential backoff (1s, 2s, 4s, 8s)
    2. \n
  2. Check GET /health to see if the server is up
    3. \n
  3. If persistent, report the error
    4. \n
\n

503 Service Unavailable

\n

Server is temporarily down (e.g. during deployment, database migration).

\n

Fix: Wait and retry. Check GET /health.

\n

Recovery Patterns

\n

Retry with exponential 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")

Auth error handling

\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

Common Error Scenarios

\n

"Mind Key fehlt oder ungültig"

\n\n

"Route not found"

\n\n

"Rate limit exceeded"

\n\n

Next Steps

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