> For the complete documentation index, see [llms.txt](https://docs.apismart.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apismart.ai/documentation/zh-tw/yi-nan-pai-jie/http-zhuang-tai-ma-yu-api-cuo-wu.md).

# HTTP 狀態碼與 API 錯誤

了解 ApiSmart 的 HTTP 狀態碼、API 錯誤碼、常見原因，以及建議的處理與重試策略。

ApiSmart 使用標準 HTTP 狀態碼，並搭配 API 特定錯誤代碼，來表示請求是否成功，以及若未成功，失敗原因為何。

處理錯誤時，先檢查 **HTTP 狀態碼**，再使用回傳的錯誤 `代碼` 和訊息進行更詳細的診斷。

某些模型供應商可能會隨時間回傳額外的錯誤代碼，因此你的應用程式也應能優雅地處理未知的錯誤代碼。

### 🚦 錯誤處理一覽

| HTTP 狀態 | 類別        | 要重試嗎？          |
| ------- | --------- | -------------- |
| `400`   | 請求或參數無效   | 否 — 先修正請求      |
| `401`   | 驗證失敗      | 否 — 檢查 API Key |
| `402`   | 餘額不足      | 否 — 先加值        |
| `403`   | 存取或模型能力問題 | 通常不用           |
| `404`   | 任務或資源找不到  | 通常不用           |
| `410`   | 影片結果不可用   | 通常不用           |
| `429`   | 超出速率限制    | 是 — 請先等待再重試    |
| `500`   | 內部伺服器錯誤   | 是 — 謹慎重試       |
| `502`   | 閘道或上游錯誤   | 通常是            |
| `503`   | 服務暫時無法使用  | 是              |
| `504`   | 閘道逾時      | 是              |

不要自動重試每一個失敗的請求。

驗證錯誤、無效參數、不支援的解析度，以及存取錯誤，通常都應先修正後再發送下一個請求。

### 400 — 錯誤請求

一個 `400` 回應表示因其參數或格式無效而無法處理該請求。

可能的錯誤代碼包括：

| 代碼                       | 意義            |
| ------------------------ | ------------- |
| `invalid_request_error`  | 必要參數遺漏或請求無效   |
| `invalid_json`           | JSON 請求主體格式錯誤 |
| `unsupported_resolution` | 所請求的解析度不支援    |
| `InvalidParameter`       | 底層模型服務拒絕了某個參數 |

#### 如何排查問題

檢查：

* 必要的請求參數
* JSON 語法
* 參數類型與值
* 模型特定的參數要求
* 支援的圖片或影片解析度
* 輸入素材限制與格式

在未修正無效參數之前，不要重複重試同一個請求。

### 401 — 無效的 API Key

可能的錯誤代碼：

`invalid_api_key`

用於驗證此請求的 API Key 無效。

確認請求包含：

```http
Authorization: Bearer <your-api-key>
```

確認：

* API Key 正確
* API Key 尚未被刪除或停用
* 該 `Bearer` 前綴存在
* 沒有多餘空格或遺漏字元
* 你的應用程式使用的是預期的環境變數

切勿在截圖、日誌、公開儲存庫或支援請求中曝光你的完整 API Key。

有關 API Key 管理，請參閱 [**建立與管理 API Key**](https://docs.apismart.ai/documentation/zh-tw/huan-ying-shi-yong-apismart/api-jin-yue/jian-li-bing-guan-li-api-jin-yue.md).

### 402 — 餘額不足

可能的錯誤代碼：

`insufficient_quota`

這表示帳戶沒有足夠的可用餘額來完成請求。

重試前：

1. 查看你目前的錢包餘額。
2. 檢視近期的使用量與費用。
3. 必要時加值。
4. 在有足夠餘額後再重試請求。

參見 [**加值與了解錢包點數**](https://docs.apismart.ai/documentation/zh-tw/zhang-hu-yu-qian-bao/jia-zhi-yu-liao-jie-qian-baoedu.md) 以及 [**使用記錄與費用**](https://docs.apismart.ai/documentation/zh-tw/api-shi-yong-liang/shi-yong-ji-lu-yu-cheng-ben.md) 以了解更多資訊。

### 403 — 存取與模型錯誤

一個 `403` 回應表示請求已通過驗證，但在目前情境下無法使用所請求的模型、端點或資源。

#### `model_not_allowed`

所選模型不適用於你的 API Key 或帳戶。

使用以下方式查看目前可用的模型：

```bash
curl https://gw.apismart.ai/v1/models \\
  -H "Authorization: Bearer <your-api-key>"
```

使用回傳的 `data[].id` 完全依照原樣。

#### `model_not_image_capable`

所選模型不能用於圖片生成 API。

請改用支援的圖片模型。

#### `model_not_video_capable`

所選模型不能用於影片生成 API。

請改用支援的影片模型。

#### `AccessDenied`

已拒絕對所選模型或操作的存取。

請確認你的帳戶與請求支援該模型和 API 端點。

#### `asset_not_owned`

影片請求參照了一個 `asset://` 不屬於目前帳戶的資源。

以此錯誤遭拒絕的請求會 **不會** 產生生成費用。

僅使用與發出請求的帳戶相關聯且已驗證的素材。

### 404 — 找不到資源

ApiSmart 使用不同的 `404` 錯誤，取決於正在存取的資源。

#### `task_not_found`

所請求的影片任務不存在。

檢查：

* 任務 ID 正確
* 你正在查詢預期的任務
* 任務建立後 ID 已正確儲存

影片任務狀態查詢方式：

```
GET /v1/video/tasks/{id}
```

#### `resource_not_found`

真人素材操作參照了一個資源或素材群組，該資源或群組：

* 不存在，或
* 不屬於目前帳戶

在重試前，請確認素材或群組識別碼與帳戶所有權。

### 410 — 影片不可用

可能的錯誤代碼：

`video_not_available`

所請求的影片結果已不再可用，或相關影片任務未成功完成。

當這種情況發生時，請檢查原始影片任務：

```
GET /v1/video/tasks/{id}
```

確認其最終狀態是否為：

* `成功`
* `失敗`
* `已取消`
* `已過期`

不要假設每個已建立的影片任務都會有可下載的影片內容。

有關影片任務行為，請參閱 [**影片生成 API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/ying-pian-sheng-cheng-api.md).

### 429 — 超出速率限制

可能的錯誤代碼：

`rate_limit_error`

一個 `429` 回應表示已達服務速率限制。

不要立即重複送出請求重試。

改為：

* 降低請求頻率
* 在重試前加入延遲
* 使用指數退避
* 避免建立會產生額外流量的重試迴圈

簡單的退避序列可能如下：

```
1 秒 → 2 秒 → 4 秒 → 8 秒
```

你的應用程式應在合理次數後停止重試。

### 500 — 內部伺服器錯誤

可能的錯誤代碼包括：

* `internal_error`
* `InternalServerError`

這些表示內部服務錯誤。

不同於 `400` 請求錯誤， `500` 此回應可能是暫時性的。

建議的處理方式：

1. 若可取得，請保留原始 Request ID。
2. 稍等片刻。
3. 以指數退避方式重試。
4. 在有限次數後停止。
5. 如果問題持續，請聯絡 ApiSmart 支援。

避免無限制的自動重試。

### 502 — 閘道或上游錯誤

可能的錯誤包括：

* `proxy_error`
* `BadGateway`

一個 `502` 通常表示 ApiSmart 與上游模型服務或網路層之間出現暫時性問題。

重試前請使用指數退避。

#### 特殊情況：真人驗證

在使用 Seedance 經驗證的真人素材工作流程時，驗證結果請求可能會回傳：

`502 upstream_error`

而使用者尚未 **完成手機驗證流程**.

在這個特定工作流程中，回應不一定代表平台故障。

請先透過提供的 `H5Link` 完成驗證，再次擷取結果。

如果需要輪詢，請使用大約 **5–10 秒** 的間隔，並將總輪詢期間維持在驗證權杖的有效期內。

此特殊行為適用於真人驗證工作流程，不應被視為每個 `502` 回應的一般意義。

### 503 — 服務暫時無法使用

可能的錯誤代碼包括：

| 代碼                                | 意義             |
| --------------------------------- | -------------- |
| `provider_not_available`          | 模型供應商暫時無法使用    |
| `quota_service_unavailable`       | 配額或餘額服務暫時無法使用  |
| `proxy_unavailable`               | 代理或閘道依賴項暫時無法使用 |
| `asset_owner_service_unavailable` | 素材所有權服務暫時無法使用  |

這些錯誤通常表示相依服務出現暫時性問題。

適當時：

1. 檢查回應中的 `Retry-After`.
2. 在提供指定時間後再等待。
3. 使用指數退避重試。
4. 限制重試總次數。

如果有一個 `503` 在變更模型 ID 後出現時，也請確認模型 ID 與文件中的值完全一致。

### 504 — 閘道逾時

可能的錯誤代碼：

`GatewayTimeout`

一個 `504` 表示閘道或上游服務未能及時回應。

這可能是暫時性的。

建議的處理方式：

* 重試前先等待
* 使用指數退避
* 避免立即重複發送請求
* 在適用時，檢視你自己的用戶端逾時設定

對於同步圖片生成，你的用戶端應允許生成請求有足夠時間完成。

### 🔁 重試策略

錯誤通常可分為兩類。

#### 重試前先修正

通常不要自動重試：

* `400`
* `401`
* `402`
* 大多數 `403`
* 大多數 `404`
* `410`

這些錯誤通常需要先修正請求、驗證、餘額、存取或資源問題。

#### 重試暫時性失敗

以下情況適合採用受控重試策略：

* `429`
* `500`
* `502`
* `503`
* `504`

請使用指數退避，而不是立即重試。

例如：

```
第 1 次嘗試 → 等待 1 秒
第 2 次嘗試 → 等待 2 秒
第 3 次嘗試 → 等待 4 秒
第 4 次嘗試 → 等待 8 秒
```

如果伺服器提供一個 `Retry-After` 值，請在適用時遵循該值。

務必限制重試次數。

### 🧩 處理未知錯誤代碼

某些錯誤回應可能包含底層模型供應商回傳的代碼。

隨著供應商服務演進，這些值可能會改變，或出現新的代碼。

不要讓你的應用程式只能處理固定的已知錯誤代碼清單。

建議邏輯：

1. 檢查 HTTP 狀態碼。
2. 在可取得時，讀取回傳的 API 錯誤代碼。
3. 使用 HTTP 狀態來決定一般處理策略。
4. 記錄未知錯誤代碼以供診斷。
5. 在可取得時，保留原始錯誤訊息和 Request ID。
6. 避免將未知錯誤代碼視為成功請求。

HTTP 狀態碼應是判斷請求應修正或重試的主要訊號。

### 🔎 使用 Request ID 排查

在調查失敗的 API 呼叫時，請保留 **Request ID** ，如果可取得，請與該請求相關聯。

你也可以查看對應記錄 [**使用記錄與費用**](https://docs.apismart.ai/documentation/zh-tw/api-shi-yong-liang/shi-yong-ji-lu-yu-cheng-ben.md).

有用的排查資訊可能包括：

* Request ID
* 請求時間
* 模型
* API 端點
* HTTP 狀態
* 錯誤代碼
* 錯誤訊息

如果你聯絡 ApiSmart 支援，請提供相關的 Request ID 和錯誤資訊。

**切勿向支援團隊提供你的完整 API Key。**

### 📋 錯誤代碼參考

| HTTP 狀態 | 錯誤代碼                              | 說明                   |
| ------- | --------------------------------- | -------------------- |
| `400`   | `invalid_request_error`           | 請求參數遺漏或無效            |
| `400`   | `invalid_json`                    | 無效的 JSON 請求主體        |
| `400`   | `unsupported_resolution`          | 解析度不支援               |
| `400`   | `InvalidParameter`                | 模型服務拒絕了某個參數          |
| `401`   | `invalid_api_key`                 | 無效的 API Key          |
| `402`   | `insufficient_quota`              | 帳戶餘額不足               |
| `403`   | `model_not_allowed`               | 模型不可用                |
| `403`   | `model_not_image_capable`         | 模型不支援圖片端點            |
| `403`   | `model_not_video_capable`         | 模型不支援影片端點            |
| `403`   | `AccessDenied`                    | 已拒絕對模型或操作的存取         |
| `403`   | `asset_not_owned`                 | 所參照的真人素材不屬於該帳戶       |
| `404`   | `task_not_found`                  | 影片任務不存在              |
| `404`   | `resource_not_found`              | 真人素材或素材群組不存在，或不屬於該帳戶 |
| `410`   | `video_not_available`             | 影片任務不成功或結果不可用        |
| `429`   | `rate_limit_error`                | 服務速率限制已超過            |
| `500`   | `internal_error`                  | 內部伺服器錯誤              |
| `500`   | `InternalServerError`             | 內部伺服器錯誤              |
| `502`   | `proxy_error`                     | 模型服務或網路層錯誤           |
| `502`   | `BadGateway`                      | 上游閘道錯誤               |
| `502`\* | `upstream_error`                  | 真人工作流程中的特殊驗證狀態回應     |
| `503`   | `provider_not_available`          | 模型供應商暫時無法使用          |
| `503`   | `quota_service_unavailable`       | 配額服務暫時無法使用           |
| `503`   | `proxy_unavailable`               | 代理依賴項暫時無法使用          |
| `503`   | `asset_owner_service_unavailable` | 素材所有權服務暫時無法使用        |
| `504`   | `GatewayTimeout`                  | 上游服務逾時               |

\* `upstream_error` 是專門針對真人驗證流程所記錄，且在驗證尚未完成時適用。

### ✅ 錯誤處理檢查清單

在將 API 請求視為永久失敗之前：

* 檢查 HTTP 狀態碼
* 讀取回傳的錯誤代碼和訊息
* 確認 API Key 有效
* 驗證模型 ID
* 驗證模型支援該端點
* 檢查必要的請求參數
* 檢查你可用的餘額
* 檢視模型特定的解析度與輸入需求
* 暫時性失敗才重試 `5xx` 或 `429` 錯誤僅搭配受控退避重試
* 保留 Request ID 以便排查
* 優雅地處理未知錯誤代碼

### ➡️ 下一步

繼續：

* [**模型與模型 ID**](https://docs.apismart.ai/documentation/zh-tw/mo-xing-yu-jia-ge/mo-xing-yu-mo-xing-id.md) — 驗證模型 ID 與可用性
* [**使用記錄與費用**](https://docs.apismart.ai/documentation/zh-tw/api-shi-yong-liang/shi-yong-ji-lu-yu-cheng-ben.md) — 調查請求層級的錯誤與成本
* [**建立與管理 API Key**](https://docs.apismart.ai/documentation/zh-tw/huan-ying-shi-yong-apismart/api-jin-yue/jian-li-bing-guan-li-api-jin-yue.md) — 管理驗證憑證
* [**餘額與用量限制問題**](https://docs.apismart.ai/documentation/zh-tw/yi-nan-pai-jie/yueyu-shi-yong-xian-zhi-wen-ti.md) — 排查與餘額相關的失敗
