# Errors & Error Handling

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 構文
- 無効な enum 値（例：カテゴリの誤り）

```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
- Mind Key が必要な場所で JWT を使用（またはその逆）

```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

サーバーエラーです。本来発生すべきではありません。発生した場合はバグです。

**対策：**

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 invalid — alert user
        raise AuthError("Mind Key invalid or expired")
    return r
```

## よくあるエラーシナリオ

### "Mind Key fehlt oder ungültig"

- `Authorization` ヘッダーを忘れた
- `?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 Overview](/docs/api/overview)
- [Rate Limits](/docs/api/rate-limits)