# API Error Codes (API 標準錯誤碼)

| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-04-25 |
| 文件版本 | V1.0 |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-25 | 定義全局標準錯誤碼與 Response 格式 | OpenCode | OpenCode |

---

## 1. 錯誤 Response 格式

所有 API 錯誤回應必須遵循以下 JSON 結構：

```json
{
  "success": false,
  "error": {
    "code": "E001_NOT_FOUND",
    "message": "找不到指定的資源",
    "details": {
      "resource": "file_uuid",
      "value": "abc-123"
    }
  }
}
```

---

## 2. 錯誤碼列表

### 2.1 通用錯誤 (E0xx)

| 錯誤碼 | HTTP 狀態 | 說明 |
|--------|-----------|------|
| `E001_NOT_FOUND` | 404 | 找不到資源 (File, Identity, Chunk...) |
| `E002_DUPLICATE` | 409 | 資源已存在 (例如：重複註冊 File UUID) |
| `E003_VALIDATION` | 400 | 請求參數驗證失敗 (缺欄位、格式錯誤) |
| `E004_UNAUTHORIZED` | 401 | 無效的 API Key 或 Token |
| `E005_INTERNAL` | 500 | 系統內部錯誤 (資料庫連線失敗等) |

### 2.2 處理器相關 (E1xx)

| 錯誤碼 | HTTP 狀態 | 說明 |
|--------|-----------|------|
| `E101_PROCESSOR_FAIL` | 500 | Python 腳本執行失敗 (返回非 0 狀態碼) |
| `E102_TIMEOUT` | 504 | 處理超時 (例如：長影片 ASR 處理過久) |
| `E103_RESUME_FAIL` | 500 | 續傳失敗 (找不到 Checkpoint 檔案) |
| `E104_NO_VIDEO` | 400 | 找不到影片路徑 |

### 2.3 身份與 Face (E2xx)

| 錯誤碼 | HTTP 狀態 | 說明 |
|--------|-----------|------|
| `E201_FACE_NOT_FOUND` | 404 | 找不到指定的 Face Pre-chunk |
| `E202_MERGE_CONFLICT` | 409 | Identity 合併衝突 |
| `E203_CANDIDATE_EMPTY` | 404 | 沒有待確認的 Candidates |

---

## 3. 實作建議 (Rust Axum)

在 `src/api/server.rs` 中，建議使用自訂錯誤型別來統一處理：

```rust
#[derive(Debug)]
pub enum AppError {
    NotFound(String),
    Validation(String),
    Internal(anyhow::Error),
}

impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        let (code, message, status) = match self {
            AppError::NotFound(msg) => ("E001_NOT_FOUND", msg, StatusCode::NOT_FOUND),
            AppError::Validation(msg) => ("E003_VALIDATION", msg, StatusCode::BAD_REQUEST),
            AppError::Internal(e) => ("E005_INTERNAL", e.to_string(), StatusCode::INTERNAL_SERVER_ERROR),
        };

        (status, Json(serde_json::json!({
            "success": false,
            "error": {
                "code": code,
                "message": message
            }
        }))).into_response()
    }
}
```

---

## 版本資訊

- 版本: V1.0
- 建立日期: 2026-04-25
