# 狀態碼

> WayinVideo API 的 HTTP 狀態碼與回應格式說明。

## 狀態碼

API 使用標準 HTTP 狀態碼，回應本體格式依狀態碼而異。

---

## 200 OK

請求成功。回應本體為 JSON，資料內容包裝在 `data` 欄位中。

**範例**

```json
{
  "data": {
    "project_id": "prj06928fdjqqaza",
    "name": "Sample project name",
    "status": "SUCCEEDED"
  }
}
```

`data` 的結構依端點而異，詳情請參閱各 API 的說明文件。

---

## 400 Bad Request

客戶端錯誤——例如參數無效、影片格式不支援，或其他輸入問題。請查看 `message` 欄位，修正請求後重試。

| 欄位 | 類型 | 說明 |
|------|------|------|
| `trace_id` | string | 用於診斷與客服支援的唯一識別碼 |
| `message` | string | 人類可讀的錯誤描述 |

**範例**

```json
{
  "message": "the error message",
  "trace_id": "the_trace_id"
}
```

---

## API 點數不足

帳戶的 API 點數不足以提交該任務時，API 回傳 **400 Bad Request**。任務不會建立，也不會扣除點數。回應正文包含 `message` 與 `trace_id`。

**範例**

```json
{
  "message": "Your API units are insufficient. Please purchase more to continue: https://wayin.ai/wayinvideo/api-dashboard",
  "trace_id": "the_trace_id"
}
```

費率見 [計費說明](https://wayin.ai/zh-tw/api-docs/pricing/)。

---

## 500 Internal Server Error

伺服器端錯誤——系統內部發生了非預期的錯誤。若問題持續發生，請帶著 `trace_id` 聯繫客服。

| 欄位 | 類型 | 說明 |
|------|------|------|
| `trace_id` | string | 用於診斷與客服支援的唯一識別碼 |
| `message` | string | 人類可讀的錯誤描述 |

**範例**

```json
{
  "message": "the error message",
  "trace_id": "the_trace_id"
}
```

---

## 403 Forbidden

驗證失敗（API 金鑰無效或缺少）。回應本體包含：

| 欄位 | 類型 | 說明 |
|------|------|------|
| `timestamp` | string | 回應時間（ISO 8601 格式） |
| `status` | number | HTTP 狀態碼（403） |
| `error` | string | 簡短錯誤類型（例如 `"Forbidden"`） |
| `path` | string | 請求路徑 |

**範例**

```json
{
  "timestamp": "2026-03-13T07:58:46.156+00:00",
  "status": 403,
  "error": "Forbidden",
  "path": "/api/v2/clips"
}
```

---

## 429 Too Many Requests

請求因速率限制或並發限制而被拒絕。回應本體格式與 403 相同：`timestamp`、`status`、`error`、`path`。

**範例**

```json
{
  "timestamp": "2026-03-10T15:52:01.610+00:00",
  "status": 429,
  "error": "Too Many Requests",
  "path": "/api/v2/clips/results/prjxxx"
}
```

請參閱 [速率限制](https://wayin.ai/zh-tw/api-docs/rate-limits/) 了解限制數值與避免 429 的方法。