Synapse は標準的な HTTP ステータスコードと一貫したエラーレスポンス形式を使用します。本ページではエラーの解釈と復旧方法を説明します。
\nすべてのエラーは以下の構造の JSON を返します。
\n{\n "statusCode": 401,\n "error": "Unauthorized",\n "message": "Mind Key fehlt oder ungültig.",\n "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"\n}| フィールド | \n説明 | \n
|---|---|
statusCode | \nHTTP ステータスコード | \n
error | \nHTTP ステータス名 | \n
message | \n人間が読めるエラーの説明 | \n
docs | \n関連ドキュメントの URL（該当する場合） | \n
成功。リクエストが正常に処理されました。
\n成功。新しいリソースが作成されました（例：POST /memory）。
成功。レスポンスボディはありません（例：DELETE /memory/:id）。
リクエストの形式が不正です。よくある原因：
\n{\n "statusCode": 400,\n "error": "Bad Request",\n "message": "category must be one of: identity, preference, fact, project, skill, mistake, context, note, credentials"\n}対策： リクエストボディを API ドキュメントと照合してください。すべての必須フィールドが存在し、有効な値であることを確認します。
\n認証に失敗しました。よくある原因：
\nAuthorization ヘッダーの欠落{\n "statusCode": 401,\n "error": "Unauthorized",\n "message": "Mind Key fehlt oder ungültig.",\n "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"\n}対策： トークンを確認してください。Authentication を参照。
\n認証は成功していますが、このアクションの実行が許可されていません。よくある原因：
\n対策： このエンドポイントに対して正しいトークン種別を使用しているか確認してください。
\n要求されたパスまたはリソースが存在しません。
\n{\n "statusCode": 404,\n "error": "Not Found",\n "message": "Route GET /memory/list not found",\n "docs": "https://synapse.schaefer.zone/docs/api/errors"\n}対策： GET /endpoints を呼び出して有効なエンドポイントのリストを確認してください。URL をリストと文字単位で比較してください。
リクエストが既存の状態と競合しています。よくある原因：
\n対策： 別の値を使用するか、PUT で既存リソースを更新してください。
レート制限に達しました。?key= クエリパラメータ認証（60 回/分）にのみ適用されます。
{\n "statusCode": 429,\n "error": "Too Many Requests",\n "message": "Rate limit exceeded. Use Authorization header for unlimited access."\n}レスポンスヘッダー：
\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42対策： Authorization: Bearer ヘッダーに切り替える（レート制限なし）、または Retry-After 秒待機してください。
サーバーエラーです。本来発生すべきではありません。発生した場合はバグです。
\n対策：
\nGET /health でサーバー稼働状況を確認サーバーが一時的に停止しています（デプロイ中やデータベースマイグレーション中など）。
\n対策： 待機して再試行してください。GET /health を確認。
import time\nimport requests\n\ndef call_with_retry(url, max_retries=3):\n for attempt in range(max_retries):\n try:\n r = requests.get(url, headers={"Authorization": f"Bearer {KEY}"})\n if r.status_code == 429:\n wait = int(r.headers.get("Retry-After", 60))\n time.sleep(wait)\n continue\n if r.status_code >= 500:\n time.sleep(2 ** attempt)\n continue\n return r\n except requests.RequestException:\n time.sleep(2 ** attempt)\n raise Exception(f"Failed after {max_retries} retries")def safe_call(url, key):\n r = requests.get(url, headers={"Authorization": f"Bearer {key}"})\n if r.status_code == 401:\n # Mind Key invalid — alert user\n raise AuthError("Mind Key invalid or expired")\n return rAuthorization ヘッダーを忘れた?key= を使用したがキーが間違っているGET /memory と POST /memory）GET /endpoints で有効なパスを確認?key= を使用して 60 回/分を超えたAuthorization: Bearer ヘッダーに切り替える