{"title":"API 常见问题","slug":"api-faq","category":"faq","summary":"常见 API 问题 — 认证、限速、错误处理、端点发现。","audience":["human","llm"],"tags":["faq","api","troubleshooting"],"difficulty":"beginner","updated":"2026-06-27","word_count":205,"read_minutes":1,"lang":"zh","translated":true,"requested_lang":"zh","content_markdown":"\n# API 常见问题\n\n关于 Synapse API 的常见问题。\n\n## 如何认证？\n\n两种方式：\n\n1. **Mind Key**（用于数据端点）：`Authorization: Bearer mk_...`\n2. **JWT**（用于账户端点）：`Authorization: Bearer eyJ...`\n\n或通过查询参数（限速 60 次/分钟）：`?key=mk_...`\n\n参见 [Authentication](/docs/getting-started/authentication)。\n\n## Mind Key 和 JWT 有何区别？\n\n- **Mind Key**：租户范围，永不过期，用于记忆/聊天/任务数据\n- **JWT**：用户范围，7 天过期，用于账户/Mind 管理\n\n参见 [Mind Key 与 JWT](/docs/getting-started/mind-key-vs-jwt)。\n\n## 为什么收到 401 Unauthorized？\n\n常见原因：\n\n1. 缺少 `Authorization` 头\n2. Mind Key 无效（确认它以 `mk_` 开头）\n3. 在需要 Mind Key 的地方用了 JWT（或反之）\n4. Mind Key 已被吊销\n\n**修复：** 校验你的令牌。参见 [Authentication](/docs/getting-started/authentication)。\n\n## 为什么收到 404 Not Found？\n\n你用了错误的端点路径。Synapse 只有 `GET /endpoints` 中列出的路径。\n\n**修复：** 调用 `GET /endpoints` 查看所有有效路径。不要猜测。\n\n## 为什么收到 429 Too Many Requests？\n\n你使用了 `?key=` 查询参数认证，它被限速到 60 次/分钟。\n\n**修复：** 改用 `Authorization: Bearer` 头（无限制）。\n\n参见 [限速](/docs/api/rate-limits)。\n\n## 如何列出所有端点？\n\n```bash\ncurl https://synapse.schaefer.zone/endpoints\ncurl https://synapse.schaefer.zone/endpoints?format=text\n```\n\n## 如何找到正确的端点？\n\n1. 查看 `GET /endpoints` 获取机器可读列表\n2. 查看 `GET /help` 获取完整 API 文档\n3. 浏览 `GET /docs` 查看文档系统\n4. 使用 `GET /openapi.json` 获取 OpenAPI 3.0 规范\n\n## 能用 GET 代替 POST 吗？\n\n部分 POST 端点有对应的 GET 版本，供只能使用 URL 的工具使用：\n\n- `POST /memory` ↔ `GET /memory/store?content=...`\n- `POST /mind/task` ↔ `GET /mind/task?title=...`\n- `POST /chat/reply` ↔ `GET /chat/reply?content=...`\n\n通过 `GET /endpoints` 查看可用的 GET 变体。\n\n## 如何处理错误？\n\n所有错误都返回 JSON：\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参见 [错误与错误处理](/docs/api/errors)。\n\n## 请求体大小限制是多少？\n\n10 MB。对于更大的 payload（例如文件上传），请使用 multipart 端点。\n\n## API 支持 CORS 吗？\n\n支持。所有端点都返回：\n\n```\nAccess-Control-Allow-Origin: *\nAccess-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS\nAccess-Control-Allow-Headers: Authorization, Content-Type, X-Synapse-JWT\n```\n\n## 有 SDK 吗？\n\n有：\n\n- **Node.js**：`npm install synapse-memory-sdk`\n- **MCP**：`npx -y synapse-mcp-api@latest`\n\n详见 [API 概览](/docs/api/overview)。\n\n## 如何分页？\n\n使用 `?limit=` 和 `?offset=`：\n\n```bash\ncurl \".../memory?limit=50&offset=100\"\n```\n\n默认 limit：100。最大：500。\n\n## 能按分类或标签过滤记忆吗？\n\n可以：\n\n```bash\ncurl \".../memory?category=project\"\ncurl \".../memory?tag=docker\"\ncurl \".../memory/by-tag?tag=production\"\n```\n\n## 如何搜索记忆？\n\n两种方式：\n\n1. **FTS5 关键词搜索**：`GET /memory/search?q=docker+swarm`\n2. **语义搜索**：`GET /memory/semantic-search?q=container+orchestration`\n\n参见 [FTS5 搜索](/docs/concepts/fts5-search) 与 [语义搜索](/docs/concepts/semantic-search)。\n\n## 如何更新记忆？\n\n用相同的 `category` + `key` 发起 `POST /memory` — 已存在的记忆会被更新，不会重复。\n\n```bash\n# 初始存储\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael\"}'\n\n# 更新（相同 key）\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael Schäfer\"}'\n```\n\n## 如何删除记忆？\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer $KEY\" \\\n https://synapse.schaefer.zone/memory/mem_001\n```\n\n## 能批量删除吗？\n\n可以：\n\n```bash\ncurl -X POST .../memory/bulk-delete \\\n -d '{\"ids\": [\"mem_001\", \"mem_002\", \"mem_003\"]}'\n```\n\n## 下一步\n\n- [API 概览](/docs/api/overview)\n- [错误与错误处理](/docs/api/errors)\n- [Authentication](/docs/getting-started/authentication)\n","content_html":"

API 常见问题

\n

关于 Synapse API 的常见问题。

\n

如何认证？

\n

两种方式：

\n
    \n
  1. Mind Key（用于数据端点）：Authorization: Bearer mk_...
    2. \n
  2. JWT（用于账户端点）：Authorization: Bearer eyJ...
    3. \n
\n

或通过查询参数（限速 60 次/分钟）：?key=mk_...

\n

参见 Authentication。

\n

Mind Key 和 JWT 有何区别？

\n\n

参见 Mind Key 与 JWT。

\n

为什么收到 401 Unauthorized？

\n

常见原因：

\n
    \n
  1. 缺少 Authorization 头
    2. \n
  2. Mind Key 无效（确认它以 mk_ 开头）
    3. \n
  3. 在需要 Mind Key 的地方用了 JWT（或反之）
    4. \n
  4. Mind Key 已被吊销
    5. \n
\n

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

\n

为什么收到 404 Not Found？

\n

你用了错误的端点路径。Synapse 只有 GET /endpoints 中列出的路径。

\n

修复： 调用 GET /endpoints 查看所有有效路径。不要猜测。

\n

为什么收到 429 Too Many Requests？

\n

你使用了 ?key= 查询参数认证，它被限速到 60 次/分钟。

\n

修复： 改用 Authorization: Bearer 头（无限制）。

\n

参见 限速。

\n

如何列出所有端点？

\n
curl https://synapse.schaefer.zone/endpoints\ncurl https://synapse.schaefer.zone/endpoints?format=text

如何找到正确的端点？

\n
    \n
  1. 查看 GET /endpoints 获取机器可读列表
    2. \n
  2. 查看 GET /help 获取完整 API 文档
    3. \n
  3. 浏览 GET /docs 查看文档系统
    4. \n
  4. 使用 GET /openapi.json 获取 OpenAPI 3.0 规范
    5. \n
\n

能用 GET 代替 POST 吗？

\n

部分 POST 端点有对应的 GET 版本，供只能使用 URL 的工具使用：

\n\n

通过 GET /endpoints 查看可用的 GET 变体。

\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

10 MB。对于更大的 payload（例如文件上传），请使用 multipart 端点。

\n

API 支持 CORS 吗？

\n

支持。所有端点都返回：

\n
Access-Control-Allow-Origin: *\nAccess-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS\nAccess-Control-Allow-Headers: Authorization, Content-Type, X-Synapse-JWT

有 SDK 吗？

\n

有：

\n\n

详见 API 概览。

\n

如何分页？

\n

使用 ?limit= 和 ?offset=：

\n
curl ".../memory?limit=50&offset=100"

默认 limit：100。最大：500。

\n

能按分类或标签过滤记忆吗？

\n

可以：

\n
curl ".../memory?category=project"\ncurl ".../memory?tag=docker"\ncurl ".../memory/by-tag?tag=production"

如何搜索记忆？

\n

两种方式：

\n
    \n
  1. FTS5 关键词搜索：GET /memory/search?q=docker+swarm
    2. \n
  2. 语义搜索：GET /memory/semantic-search?q=container+orchestration
    3. \n
\n

参见 FTS5 搜索 与 语义搜索。

\n

如何更新记忆？

\n

用相同的 category + key 发起 POST /memory — 已存在的记忆会被更新，不会重复。

\n
# 初始存储\ncurl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael"}'\n\n# 更新（相同 key）\ncurl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael Schäfer"}'

如何删除记忆？

\n
curl -X DELETE -H "Authorization: Bearer $KEY" \\\n     https://synapse.schaefer.zone/memory/mem_001

能批量删除吗？

\n

可以：

\n
curl -X POST .../memory/bulk-delete \\\n  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'

下一步

\n\n","urls":{"html":"/docs/faq/api-faq","text":"/docs/faq/api-faq?format=text","json":"/docs/faq/api-faq?format=json","llm":"/docs/faq/api-faq?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}