jettcheng1018
/
dramaling-app
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
dramaling-app/docs/04_technical/api/errors.md

304 lines
10 KiB
Markdown
Raw Blame History

# 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)
Reference in New Issue View Git Blame Copy Permalink