# 错误与错误处理

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

## 错误响应格式

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

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

| 字段 | 说明 |
|-------|-------------|
| `statusCode` | HTTP 状态码 |
| `error` | HTTP 状态名称 |
| `message` | 人类可读的错误描述 |
| `docs` | 指向相关文档的 URL（如适用） |

## HTTP 状态码

### 200 OK

成功。请求被正确处理。

### 201 Created

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

### 204 No Content

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

### 400 Bad Request

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

- 缺少必填的 JSON 字段
- 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（或反之）

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

**修复：** 校验你的令牌。参见 [Authentication](/docs/getting-started/authentication)。

### 403 Forbidden

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

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

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

### 404 Not Found

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

> [!CRITICAL]
> **不要猜测端点路径。** 只有 `GET /endpoints` 中列出的路径才存在。如果收到 404，说明你用了错误的路径。

```json
{
  "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 次/分钟）。

```json
{
  "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`。

## 恢复模式

### 指数退避重试

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

### 认证错误处理

```python
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](/docs/getting-started/authentication)
- [API 概览](/docs/api/overview)
- [限速](/docs/api/rate-limits)