Errors & Error Handling

Synapse は標準的な HTTP ステータスコードと一貫したエラーレスポンス形式を使用します。本ページではエラーの解釈と復旧方法を説明します。

エラーレスポンス形式

すべてのエラーは以下の構造の JSON を返します。

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

HTTP ステータスコード

200 OK

成功。リクエストが正常に処理されました。

201 Created

成功。新しいリソースが作成されました（例：POST /memory）。

204 No Content

成功。レスポンスボディはありません（例：DELETE /memory/:id）。

400 Bad Request

リクエストの形式が不正です。よくある原因：

• 必須 JSON フィールドの欠落
• 無効な JSON 構文
• 無効な enum 値（例：カテゴリの誤り）

{
  "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 を使用（またはその逆）

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

対策： トークンを確認してください。Authentication を参照。

403 Forbidden

認証は成功していますが、このアクションの実行が許可されていません。よくある原因：

• 他のユーザーの mind を削除しようとした
• Mind Key でメモリを検証しようとした（JWT が必要）
• mind が無効化されている

対策： このエンドポイントに対して正しいトークン種別を使用しているか確認してください。

404 Not Found

要求されたパスまたはリソースが存在しません。

{
  "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 回/分）にのみ適用されます。

{
  "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 を確認。

復旧パターン

指数バックオフでの再試行

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

認証エラーの処理

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
• API Overview
• Rate Limits