# API 常见问题
SUMMARY: 常见 API 问题 — 认证、限速、错误处理、端点发现。

API 常见问题
关于 Synapse API 的常见问题。
如何认证？
两种方式：
1. Mind Key（用于数据端点）：
2. JWT（用于账户端点）：
或通过查询参数（限速 60 次/分钟）：
参见 Authentication。
Mind Key 和 JWT 有何区别？
- Mind Key：租户范围，永不过期，用于记忆/聊天/任务数据
- JWT：用户范围，7 天过期，用于账户/Mind 管理
参见 Mind Key 与 JWT。
为什么收到 401 Unauthorized？
常见原因：
1. 缺少  头
2. Mind Key 无效（确认它以  开头）
3. 在需要 Mind Key 的地方用了 JWT（或反之）
4. Mind Key 已被吊销
修复： 校验你的令牌。参见 Authentication。
为什么收到 404 Not Found？
你用了错误的端点路径。Synapse 只有  中列出的路径。
修复： 调用  查看所有有效路径。不要猜测。
为什么收到 429 Too Many Requests？
你使用了  查询参数认证，它被限速到 60 次/分钟。
修复： 改用  头（无限制）。
参见 限速。
如何列出所有端点？
[CODE BLOCK]
如何找到正确的端点？
1. 查看  获取机器可读列表
2. 查看  获取完整 API 文档
3. 浏览  查看文档系统
4. 使用  获取 OpenAPI 3.0 规范
能用 GET 代替 POST 吗？
部分 POST 端点有对应的 GET 版本，供只能使用 URL 的工具使用：
-  ↔ 
-  ↔ 
-  ↔ 
通过  查看可用的 GET 变体。
如何处理错误？
所有错误都返回 JSON：
[CODE BLOCK]
参见 错误与错误处理。
请求体大小限制是多少？
10 MB。对于更大的 payload（例如文件上传），请使用 multipart 端点。
API 支持 CORS 吗？
支持。所有端点都返回：
[CODE BLOCK]
有 SDK 吗？
有：
- Node.js：
- MCP：
详见 API 概览。
如何分页？
使用  和 ：
[CODE BLOCK]
默认 limit：100。最大：500。
能按分类或标签过滤记忆吗？
可以：
[CODE BLOCK]
如何搜索记忆？
两种方式：
1. FTS5 关键词搜索：
2. 语义搜索：
参见 FTS5 搜索 与 语义搜索。
如何更新记忆？
用相同的  +  发起  — 已存在的记忆会被更新，不会重复。
[CODE BLOCK]
如何删除记忆？
[CODE BLOCK]
能批量删除吗？
可以：
[CODE BLOCK]
下一步
- API 概览
- 错误与错误处理
- Authentication