# Errors & Error Handling
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.

Errors & Error Handling
Synapse は標準的な HTTP ステータスコードと一貫したエラーレスポンス形式を使用します。本ページではエラーの解釈と復旧方法を説明します。
エラーレスポンス形式
すべてのエラーは以下の構造の JSON を返します。
[CODE BLOCK]
| フィールド | 説明 |
|-------|-------------|
|  | HTTP ステータスコード |
|  | HTTP ステータス名 |
|  | 人間が読めるエラーの説明 |
|  | 関連ドキュメントの URL（該当する場合） |
HTTP ステータスコード
200 OK
成功。リクエストが正常に処理されました。
201 Created
成功。新しいリソースが作成されました（例：）。
204 No Content
成功。レスポンスボディはありません（例：）。
400 Bad Request
リクエストの形式が不正です。よくある原因：
- 必須 JSON フィールドの欠落
- 無効な JSON 構文
- 無効な enum 値（例：カテゴリの誤り）
[CODE BLOCK]
対策： リクエストボディを API ドキュメントと照合してください。すべての必須フィールドが存在し、有効な値であることを確認します。
401 Unauthorized
認証に失敗しました。よくある原因：
-  ヘッダーの欠落
- 無効な Mind Key または JWT
- Mind Key が必要な場所で JWT を使用（またはその逆）
[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
サーバーエラーです。本来発生すべきではありません。発生した場合はバグです。
対策：
1. 指数バックオフで再試行（1 秒、2 秒、4 秒、8 秒）
2.  でサーバー稼働状況を確認
3. 持続する場合はエラーを報告
503 Service Unavailable
サーバーが一時的に停止しています（デプロイ中やデータベースマイグレーション中など）。
対策： 待機して再試行してください。 を確認。
復旧パターン
指数バックオフでの再試行
[CODE BLOCK]
認証エラーの処理
[CODE BLOCK]
よくあるエラーシナリオ
"Mind Key fehlt oder ungültig"
-  ヘッダーを忘れた
-  を使用したがキーが間違っている
- Mind Key が必要な場所で JWT を使用している
"Route not found"
- 存在しないパスを推測した
- 動詞を誤使用（例： と ）
-  で有効なパスを確認
"Rate limit exceeded"
-  を使用して 60 回/分を超えた
-  ヘッダーに切り替える
次のステップ
- Authentication
- API Overview
- Rate Limits