错误与错误处理

Synapse 使用标准 HTTP 状态码，并提供一致的错误响应格式。本页说明如何解读错误并从中恢复。

错误响应格式

所有错误都返回如下结构的 JSON：

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

HTTP 状态码

200 OK

成功。请求被正确处理。

201 Created

成功。创建了新资源（例如 POST /memory）。

204 No Content

成功。无响应体返回（例如 DELETE /memory/:id）。

400 Bad Request

请求格式不正确。常见原因：

• 缺少必填的 JSON 字段
• JSON 语法无效
• 枚举值无效（例如分类不正确）

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

修复： 对照 API 文档检查请求体。确保所有必填字段均存在且值合法。

401 Unauthorized

认证失败。常见原因：

• 缺少 Authorization 头
• Mind Key 或 JWT 无效
• 在需要 JWT 的地方用了 Mind Key（或反之）

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

修复： 校验你的令牌。参见 Authentication。

403 Forbidden

你已认证但无权执行此操作。常见原因：

• 尝试删除他人的 Mind
• 尝试用 Mind Key 验证记忆（需要 JWT）
• Mind 已被禁用

修复： 检查你为此端点使用的令牌类型是否正确。

404 Not Found

请求的路径或资源不存在。

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

修复： 调用 GET /endpoints 查看有效端点列表。将你的 URL 与列表逐字符对比。

409 Conflict

请求与现有状态冲突。常见原因：

• 尝试用已存在的邮箱注册
• Webhook URL 重复

修复： 使用不同的值，或使用 PUT 更新已有资源。

429 Too Many Requests

你触发了限速。仅适用于 ?key= 查询参数认证（60 次/分钟）。

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

响应头：

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

修复： 改用 Authorization: Bearer 头（无限制），或等待 Retry-After 秒。

500 Internal Server Error

服务器错误。这种情况不应发生 — 如果发生，则是 Bug。

修复：

1. 使用指数退避重试（1 秒、2 秒、4 秒、8 秒）
2. 检查 GET /health 查看服务器是否在线
3. 如果持续出现，请上报该错误

503 Service Unavailable

服务器临时不可用（例如部署、数据库迁移期间）。

修复： 等待并重试。检查 GET /health。

恢复模式

指数退避重试

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

认证错误处理

def safe_call(url, key):
    r = requests.get(url, headers={"Authorization": f"Bearer {key}"})
    if r.status_code == 401:
        # Mind Key 无效 — 提醒用户
        raise AuthError("Mind Key invalid or expired")
    return r

常见错误场景

"Mind Key fehlt oder ungültig"

• 你忘记加 Authorization 头
• 你用了 ?key= 但 key 错误
• 你在需要 Mind Key 的地方用了 JWT

"Route not found"

• 你猜了一个不存在的路径
• 你用错了动词（例如 GET /memory 与 POST /memory 混淆）
• 检查 GET /endpoints 获取有效路径

"Rate limit exceeded"

• 你使用了 ?key= 并超过 60 次/分钟
• 改用 Authorization: Bearer 头

下一步

• Authentication
• API 概览
• 限速