10 KiB

Raw Blame History

API 錯誤處理規範

📋 概述

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

🔧 標準錯誤格式

錯誤回應結構

{
  "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錯誤	稍後重試

📱 錯誤回應範例

驗證錯誤

{
  "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"
  }
}

權限錯誤

{
  "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"
  }
}

資源不存在錯誤

{
  "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"
  }
}

服務無法使用錯誤

{
  "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"
  }
}

🔧 錯誤處理最佳實踐

客戶端錯誤處理

// 錯誤處理範例
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);
    }
  }
}

伺服器錯誤記錄

// 伺服器端錯誤記錄
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日
相關文檔: 共通規範, 認證API

10 KiB Raw Blame History

API 錯誤處理規範

📋 概述

🔧 標準錯誤格式

錯誤回應結構

📚 錯誤碼分類

🔐 認證相關錯誤 (1xxx)

👤 用戶管理相關錯誤 (2xxx)

💳 訂閱相關錯誤 (3xxx)

💬 對話練習相關錯誤 (4xxx)

🎮 遊戲化系統相關錯誤 (5xxx)

📚 詞彙學習相關錯誤 (6xxx)

🏆 特殊任務相關錯誤 (7xxx)

📈 語言程度相關錯誤 (8xxx)

🔄 回覆輔助相關錯誤 (9xxx)

⚙️ 系統相關錯誤 (9xxx)

📱 錯誤回應範例

驗證錯誤

權限錯誤

資源不存在錯誤

服務無法使用錯誤

🔧 錯誤處理最佳實踐

客戶端錯誤處理

伺服器錯誤記錄

📊 錯誤監控與分析

錯誤指標

告警規則

10 KiB

Raw Blame History