# API 錯誤處理規範

## 📋 概述
Drama Ling API 的統一錯誤處理機制、錯誤碼定義和錯誤回應格式。

## 🔧 標準錯誤格式

### 錯誤回應結構
```json
{
  "success": false,
  "data": null,
  "message": "操作失敗的簡短描述",
  "error": {
    "code": "SPECIFIC_ERROR_CODE",
    "message": "詳細的錯誤描述",
    "details": {
      "field": "field_name",
      "reason": "具體錯誤原因",
      "suggestion": "建議的解決方案"
    }
  },
  "meta": {
    "timestamp": "2024-09-07T12:00:00Z",
    "request_id": "req_550e8400-e29b-41d4-a716-446655440000",
    "api_version": "v1"
  }
}
```

## 📚 錯誤碼分類

### 🔐 認證相關錯誤 (1xxx)
| 錯誤碼 | HTTP狀態 | 描述 | 建議處理 |
|--------|----------|------|----------|
| `INVALID_CREDENTIALS` | 401 | 登入憑證錯誤 | 要求用戶重新輸入憑證 |
| `TOKEN_EXPIRED` | 401 | Token已過期 | 自動刷新Token或要求重新登入 |
| `TOKEN_INVALID` | 401 | Token無效或格式錯誤 | 清除本地Token並要求重新登入 |
| `TOKEN_BLACKLISTED` | 401 | Token已被列入黑名單 | 強制用戶重新登入 |
| `ACCOUNT_LOCKED` | 423 | 帳號因多次失敗嘗試被鎖定 | 顯示鎖定時間並提供密碼重設 |
| `EMAIL_EXISTS` | 409 | 電子郵件已被註冊 | 建議用戶登入或使用其他Email |
| `USERNAME_EXISTS` | 409 | 使用者名稱已存在 | 建議其他可用的使用者名稱 |
| `VALIDATION_ERROR` | 400 | 輸入資料驗證失敗 | 顯示具體的驗證錯誤訊息 |
| `SOCIAL_LOGIN_ERROR` | 400 | 第三方登入驗證失敗 | 要求用戶重試或使用其他登入方式 |

### 👤 用戶管理相關錯誤 (2xxx)
| 錯誤碼 | HTTP狀態 | 描述 | 建議處理 |
|--------|----------|------|----------|
| `USER_NOT_FOUND` | 404 | 用戶不存在 | 檢查用戶ID或要求重新登入 |
| `PROFILE_UPDATE_FAILED` | 400 | 個人資料更新失敗 | 檢查輸入資料格式 |
| `AVATAR_UPLOAD_FAILED` | 400 | 頭像上傳失敗 | 檢查檔案格式和大小 |
| `INVALID_PREFERENCES` | 400 | 偏好設定無效 | 檢查設定值範圍 |
| `USERNAME_TAKEN` | 409 | 用戶名已被使用 | 建議其他可用用戶名 |
| `AVATAR_TOO_LARGE` | 413 | 頭像檔案過大 | 要求用戶壓縮圖片 |
| `ACCOUNT_DELETION_FAILED` | 400 | 帳號刪除失敗 | 檢查密碼或聯繫客服 |

### 💳 訂閱相關錯誤 (3xxx)
| 錯誤碼 | HTTP狀態 | 描述 | 建議處理 |
|--------|----------|------|----------|
| `SUBSCRIPTION_NOT_FOUND` | 404 | 訂閱記錄不存在 | 檢查訂閱狀態 |
| `SUBSCRIPTION_EXPIRED` | 403 | 訂閱已過期 | 引導用戶續訂 |
| `SUBSCRIPTION_CANCELLED` | 403 | 訂閱已取消 | 提供重新訂閱選項 |
| `PAYMENT_VERIFICATION_FAILED` | 400 | 付款驗證失敗 | 要求用戶重新購買 |
| `RECEIPT_INVALID` | 400 | 收據無效 | 檢查收據格式或重新購買 |
| `SUBSCRIPTION_ALREADY_ACTIVE` | 409 | 訂閱已啟用 | 提示用戶當前訂閱狀態 |
| `REFUND_REQUEST_FAILED` | 400 | 退款請求失敗 | 聯繫客服處理 |

### 💬 對話練習相關錯誤 (4xxx)
| 錯誤碼 | HTTP狀態 | 描述 | 建議處理 |
|--------|----------|------|----------|
| `DIALOGUE_NOT_FOUND` | 404 | 對話記錄不存在 | 檢查對話ID |
| `SCENARIO_NOT_FOUND` | 404 | 場景不存在 | 檢查場景ID或刷新場景列表 |
| `DIALOGUE_ALREADY_COMPLETED` | 409 | 對話已完成 | 開始新的對話 |
| `INSUFFICIENT_LIFE_POINTS` | 403 | 命條不足 | 引導用戶購買或等待恢復 |
| `AI_SERVICE_UNAVAILABLE` | 503 | AI服務暫時無法使用 | 稍後重試 |
| `RESPONSE_GENERATION_FAILED` | 500 | 回應生成失敗 | 重新發送訊息 |
| `DIALOGUE_TIMEOUT` | 408 | 對話逾時 | 重新開始對話 |

### 🎮 遊戲化系統相關錯誤 (5xxx)
| 錯誤碼 | HTTP狀態 | 描述 | 建議處理 |
|--------|----------|------|----------|
| `LIFE_POINTS_INSUFFICIENT` | 403 | 命條不足 | 引導購買或等待恢復 |
| `PURCHASE_FAILED` | 400 | 道具購買失敗 | 檢查餘額或重試 |
| `REWARD_ALREADY_CLAIMED` | 409 | 獎勵已領取 | 提示用戶已領取 |
| `ACHIEVEMENT_UNLOCK_FAILED` | 500 | 成就解鎖失敗 | 稍後重試 |
| `LEADERBOARD_UPDATE_FAILED` | 500 | 排行榜更新失敗 | 稍後重試 |
| `TIME_CHALLENGE_EXPIRED` | 410 | 時光挑戰已過期 | 開始新的挑戰 |

### 📚 詞彙學習相關錯誤 (6xxx)
| 錯誤碼 | HTTP狀態 | 描述 | 建議處理 |
|--------|----------|------|----------|
| `VOCABULARY_NOT_FOUND` | 404 | 詞彙不存在 | 檢查詞彙ID |
| `REVIEW_SESSION_EXPIRED` | 410 | 複習階段已過期 | 開始新的複習 |
| `SPACED_REPETITION_ERROR` | 500 | 間隔複習計算錯誤 | 稍後重試 |
| `VOCABULARY_PROGRESS_SYNC_FAILED` | 500 | 詞彙進度同步失敗 | 稍後重試 |
| `MASTERY_UPDATE_FAILED` | 500 | 熟練度更新失敗 | 稍後重試 |

### 🏆 特殊任務相關錯誤 (7xxx)
| 錯誤碼 | HTTP狀態 | 描述 | 建議處理 |
|--------|----------|------|----------|
| `MISSION_NOT_FOUND` | 404 | 任務不存在 | 檢查任務ID |
| `MISSION_NOT_AVAILABLE` | 403 | 任務不可用 | 檢查任務條件 |
| `MISSION_ALREADY_COMPLETED` | 409 | 任務已完成 | 等待明日任務重置 |
| `MISSION_PROGRESS_UPDATE_FAILED` | 500 | 任務進度更新失敗 | 稍後重試 |
| `REWARD_CLAIM_FAILED` | 500 | 獎勵領取失敗 | 稍後重試 |
| `DAILY_RESET_FAILED` | 500 | 每日重置失敗 | 聯繫客服 |

### 📈 語言程度相關錯誤 (8xxx)
| 錯誤碼 | HTTP狀態 | 描述 | 建議處理 |
|--------|----------|------|----------|
| `LEVEL_ASSESSMENT_FAILED` | 500 | 程度評估失敗 | 稍後重試 |
| `ADVANCEMENT_CONDITIONS_NOT_MET` | 403 | 晉階條件未滿足 | 顯示所需條件 |
| `LEVEL_UPDATE_FAILED` | 500 | 程度更新失敗 | 稍後重試 |
| `PERFECT_DIALOGUE_VALIDATION_FAILED` | 400 | 滿星對話驗證失敗 | 重新檢查對話結果 |

### 🔄 回覆輔助相關錯誤 (9xxx)
| 錯誤碼 | HTTP狀態 | 描述 | 建議處理 |
|--------|----------|------|----------|
| `HINT_LIMIT_EXCEEDED` | 429 | 提示使用次數超限 | 等待重置或購買更多 |
| `TRANSLATION_SERVICE_UNAVAILABLE` | 503 | 翻譯服務暫時無法使用 | 稍後重試 |
| `SUGGESTION_GENERATION_FAILED` | 500 | 建議生成失敗 | 稍後重試 |
| `CONTEXT_ANALYSIS_FAILED` | 500 | 語境分析失敗 | 稍後重試 |

### ⚙️ 系統相關錯誤 (9xxx)
| 錯誤碼 | HTTP狀態 | 描述 | 建議處理 |
|--------|----------|------|----------|
| `INTERNAL_SERVER_ERROR` | 500 | 內部伺服器錯誤 | 稍後重試或聯繫客服 |
| `SERVICE_UNAVAILABLE` | 503 | 服務暫時無法使用 | 稍後重試 |
| `RATE_LIMIT_EXCEEDED` | 429 | 請求頻率超限 | 降低請求頻率 |
| `MAINTENANCE_MODE` | 503 | 系統維護中 | 等待維護完成 |
| `DATABASE_CONNECTION_FAILED` | 500 | 資料庫連線失敗 | 稍後重試 |
| `EXTERNAL_API_ERROR` | 502 | 外部API錯誤 | 稍後重試 |

## 📱 錯誤回應範例

### 驗證錯誤
```json
{
  "success": false,
  "data": null,
  "message": "輸入資料驗證失敗",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "註冊資料格式不正確",
    "details": {
      "email": ["Email格式無效"],
      "password": ["密碼至少需要8位字元"],
      "username": ["用戶名只能包含字母和數字"]
    }
  },
  "meta": {
    "timestamp": "2024-09-07T12:00:00Z",
    "request_id": "req_12345"
  }
}
```

### 權限錯誤
```json
{
  "success": false,
  "data": null,
  "message": "無權限存取此功能",
  "error": {
    "code": "SUBSCRIPTION_REQUIRED",
    "message": "此功能需要訂閱會員",
    "details": {
      "required_subscription": "premium",
      "current_status": "free_user",
      "upgrade_url": "/subscription/plans"
    }
  },
  "meta": {
    "timestamp": "2024-09-07T12:00:00Z",
    "request_id": "req_12345"
  }
}
```

### 資源不存在錯誤
```json
{
  "success": false,
  "data": null,
  "message": "請求的資源不存在",
  "error": {
    "code": "DIALOGUE_NOT_FOUND",
    "message": "指定的對話記錄不存在",
    "details": {
      "dialogue_id": "DLG_12345",
      "possible_reasons": [
        "對話ID錯誤",
        "對話已被刪除",
        "無權限存取此對話"
      ]
    }
  },
  "meta": {
    "timestamp": "2024-09-07T12:00:00Z",
    "request_id": "req_12345"
  }
}
```

### 服務無法使用錯誤
```json
{
  "success": false,
  "data": null,
  "message": "服務暫時無法使用",
  "error": {
    "code": "AI_SERVICE_UNAVAILABLE",
    "message": "AI對話服務暫時無法使用",
    "details": {
      "service": "openai_gpt",
      "estimated_recovery": "2024-09-07T12:30:00Z",
      "alternative_actions": [
        "稍後重試",
        "使用離線功能"
      ]
    }
  },
  "meta": {
    "timestamp": "2024-09-07T12:00:00Z",
    "request_id": "req_12345"
  }
}
```

## 🔧 錯誤處理最佳實踐

### 客戶端錯誤處理
```javascript
// 錯誤處理範例
async function handleApiCall(apiFunction) {
  try {
    const response = await apiFunction();
    return response.data;
  } catch (error) {
    const errorCode = error.response?.data?.error?.code;
    
    switch (errorCode) {
      case 'TOKEN_EXPIRED':
        // 自動刷新Token
        await refreshAuthToken();
        return await apiFunction();
        
      case 'SUBSCRIPTION_REQUIRED':
        // 引導用戶升級
        showSubscriptionModal();
        break;
        
      case 'RATE_LIMIT_EXCEEDED':
        // 等待後重試
        await delay(5000);
        return await apiFunction();
        
      default:
        // 顯示通用錯誤訊息
        showErrorMessage(error.response?.data?.error?.message);
    }
  }
}
```

### 伺服器錯誤記錄
```javascript
// 伺服器端錯誤記錄
function logError(error, request) {
  const errorLog = {
    timestamp: new Date().toISOString(),
    request_id: request.headers['x-request-id'],
    user_id: request.user?.id,
    endpoint: request.path,
    method: request.method,
    error_code: error.code,
    error_message: error.message,
    stack_trace: error.stack,
    user_agent: request.headers['user-agent']
  };
  
  logger.error('API Error', errorLog);
}
```

## 📊 錯誤監控與分析

### 錯誤指標
- **4xx錯誤率**: 客戶端錯誤百分比
- **5xx錯誤率**: 伺服器錯誤百分比  
- **回應時間**: 錯誤回應的速度
- **錯誤趨勢**: 錯誤數量隨時間變化

### 告警規則
- 5xx錯誤率 > 1% 
- Token相關錯誤激增
- 外部服務錯誤頻繁
- 特定端點錯誤率異常

---

**負責人**: 後端開發團隊  
**最後更新**: 2024年9月7日  
**相關文檔**: [共通規範](./common.md), [認證API](./authentication.md)