# 错误与错误处理
SUMMARY: HTTP 状态码、错误响应格式以及从常见错误中恢复的方法。

KEY CONTEXT:
Error format: { statusCode, error, message, docs? }
Common errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)
401 → check Mind Key/JWT, see /docs/getting-started/authentication
404 → wrong path, GET /endpoints for valid list, do NOT guess paths
429 → rate limited (?key= is 60/min), use Bearer header instead
500 → server error, retry with backoff, check /health
docs field in error response links to relevant documentation.

错误与错误处理
Synapse 使用标准 HTTP 状态码，并提供一致的错误响应格式。本页说明如何解读错误并从中恢复。
错误响应格式
所有错误都返回如下结构的 JSON：
[CODE BLOCK]
| 字段 | 说明 |
|-------|-------------|
|  | HTTP 状态码 |
|  | HTTP 状态名称 |
|  | 人类可读的错误描述 |
|  | 指向相关文档的 URL（如适用） |
HTTP 状态码
200 OK
成功。请求被正确处理。
201 Created
成功。创建了新资源（例如 ）。
204 No Content
成功。无响应体返回（例如 ）。
400 Bad Request
请求格式不正确。常见原因：
- 缺少必填的 JSON 字段
- JSON 语法无效
- 枚举值无效（例如分类不正确）
[CODE BLOCK]
修复： 对照 API 文档检查请求体。确保所有必填字段均存在且值合法。
401 Unauthorized
认证失败。常见原因：
- 缺少  头
- Mind Key 或 JWT 无效
- 在需要 JWT 的地方用了 Mind Key（或反之）
[CODE BLOCK]
修复： 校验你的令牌。参见 Authentication。
403 Forbidden
你已认证但无权执行此操作。常见原因：
- 尝试删除他人的 Mind
- 尝试用 Mind Key 验证记忆（需要 JWT）
- Mind 已被禁用
修复： 检查你为此端点使用的令牌类型是否正确。
404 Not Found
请求的路径或资源不存在。
> [!CRITICAL]
> 不要猜测端点路径。 只有  中列出的路径才存在。如果收到 404，说明你用了错误的路径。
[CODE BLOCK]
修复： 调用  查看有效端点列表。将你的 URL 与列表逐字符对比。
409 Conflict
请求与现有状态冲突。常见原因：
- 尝试用已存在的邮箱注册
- Webhook URL 重复
修复： 使用不同的值，或使用  更新已有资源。
429 Too Many Requests
你触发了限速。仅适用于  查询参数认证（60 次/分钟）。
[CODE BLOCK]
响应头：
[CODE BLOCK]
修复： 改用  头（无限制），或等待  秒。
500 Internal Server Error
服务器错误。这种情况不应发生 — 如果发生，则是 Bug。
修复：
1. 使用指数退避重试（1 秒、2 秒、4 秒、8 秒）
2. 检查  查看服务器是否在线
3. 如果持续出现，请上报该错误
503 Service Unavailable
服务器临时不可用（例如部署、数据库迁移期间）。
修复： 等待并重试。检查 。
恢复模式
指数退避重试
[CODE BLOCK]
认证错误处理
[CODE BLOCK]
常见错误场景
"Mind Key fehlt oder ungültig"
- 你忘记加  头
- 你用了  但 key 错误
- 你在需要 Mind Key 的地方用了 JWT
"Route not found"
- 你猜了一个不存在的路径
- 你用错了动词（例如  与  混淆）
- 检查  获取有效路径
"Rate limit exceeded"
- 你使用了  并超过 60 次/分钟
- 改用  头
下一步
- Authentication
- API 概览
- 限速