Synapse 使用标准 HTTP 状态码，并提供一致的错误响应格式。本页说明如何解读错误并从中恢复。
\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
|---|---|
statusCode | \nHTTP 状态码 | \n
error | \nHTTP 状态名称 | \n
message | \n人类可读的错误描述 | \n
docs | \n指向相关文档的 URL（如适用） | \n
成功。请求被正确处理。
\n成功。创建了新资源（例如 POST /memory）。
成功。无响应体返回（例如 DELETE /memory/:id）。
请求格式不正确。常见原因：
\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}修复： 对照 API 文档检查请求体。确保所有必填字段均存在且值合法。
\n认证失败。常见原因：
\nAuthorization 头{\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}修复： 校验你的令牌。参见 Authentication。
\n你已认证但无权执行此操作。常见原因：
\n修复： 检查你为此端点使用的令牌类型是否正确。
\n请求的路径或资源不存在。
\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}修复： 调用 GET /endpoints 查看有效端点列表。将你的 URL 与列表逐字符对比。
请求与现有状态冲突。常见原因：
\n修复： 使用不同的值，或使用 PUT 更新已有资源。
你触发了限速。仅适用于 ?key= 查询参数认证（60 次/分钟）。
{\n "statusCode": 429,\n "error": "Too Many Requests",\n "message": "Rate limit exceeded. Use Authorization header for unlimited access."\n}响应头：
\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42修复： 改用 Authorization: Bearer 头（无限制），或等待 Retry-After 秒。
服务器错误。这种情况不应发生 — 如果发生，则是 Bug。
\n修复：
\nGET /health 查看服务器是否在线服务器临时不可用（例如部署、数据库迁移期间）。
\n修复： 等待并重试。检查 GET /health。
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")def safe_call(url, key):\n r = requests.get(url, headers={"Authorization": f"Bearer {key}"})\n if r.status_code == 401:\n # Mind Key 无效 — 提醒用户\n raise AuthError("Mind Key invalid or expired")\n return rAuthorization 头?key= 但 key 错误GET /memory 与 POST /memory 混淆）GET /endpoints 获取有效路径?key= 并超过 60 次/分钟Authorization: Bearer 头