> 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 錯誤

當 API 請求失敗時，HTTP 狀態碼有助於辨識問題的類別。

ApiSmart 會將錯誤資訊與 HTTP 狀態碼一併回傳，以協助您排查驗證、請求、模型、餘額或服務相關問題。

在進行變更之前，請先檢閱：

* HTTP 狀態碼
* 錯誤訊息
* 請求 ID（若有）
* 相關記錄於 [**用量記錄與費用**](/documentation/zh-tw/api-shi-yong/shi-yong-ji-lu-yu-fei-yong.md)

***

### 了解錯誤回應

失敗的請求可能包含：

| 欄位       | 說明           |
| -------- | ------------ |
| HTTP 狀態碼 | 表示一般錯誤類別     |
| 錯誤訊息     | 提供失敗請求的詳細資訊  |
| 請求 ID    | 用於疑難排解的唯一識別碼 |

範例：

```json
{
  "error": {
    "message": "找不到模型。"
  }
}
```

實際回應格式可能因端點與模型而異。

***

### 常見 HTTP 狀態碼

| 狀態碼                  | 含意           | 要檢查的內容                       |
| -------------------- | ------------ | ---------------------------- |
| **400 錯誤請求**         | 請求格式或參數無效    | JSON 格式、必要欄位、模型參數            |
| **401 未授權**          | 驗證失敗         | API Token 與 Authorization 標頭 |
| **403 禁止存取**         | 此請求不被允許      | 帳戶狀態、Token 狀態或存取限制           |
| **404 找不到資源**        | 找不到所要求的資源    | API 端點或模型 ID                 |
| **408 請求逾時**         | 請求執行完成所需時間過長 | 網路連線與用戶端逾時設定                 |
| **429 請求過多**         | 請求頻率或用量限制已超出 | 請求速率、限制與 Token 使用量           |
| **500 內部伺服器錯誤**      | 伺服器端暫時性問題    | 稍後短暫等待後重試                    |
| **502 / 503 服務無法使用** | 服務暫時無法使用     | 稍候再試                         |

***

### 疑難排解前

請先檢查以下項目：

#### 1. 驗證 API 端點

確認您使用的是所選 API 的正確端點。

範例：

```
聊天完成：
POST /v1/chat/completions

圖片生成：
POST /v1/images/generations

影片生成：
POST /v1/video/tasks
```

***

#### 2. 驗證認證

請確認：

* API Token 有效
* Authorization 標頭格式正確
* Token 尚未被停用或刪除

如有認證相關問題，請參閱：

[**API Token 與驗證問題**](/documentation/zh-tw/yi-nan-pai-jie/api-quan-zhang-yu-yan-zheng-wen-ti.md)

***

#### 3. 驗證模型設定

請檢查：

* 正確的模型 ID
* 模型 ID 的大小寫
* 支援的請求欄位
* 可用的模型參數

請務必使用所選模型中顯示的確切端點、模型 ID、請求結構與支援值。 **程式碼範例**.

如有模型相關問題，請參閱：

[**模型與請求錯誤**](/documentation/zh-tw/yi-nan-pai-jie/mo-xing-yu-qing-qiu-cuo-wu.md)

***

#### 4. 檢查餘額與用量

某些請求可能會失敗，因為：

* 目前餘額不足
* 已達 API Token 使用限制
* 所選模型需要更高的餘額

如有計費相關問題，請參閱：

[**餘額與用量限制問題**](/documentation/zh-tw/yi-nan-pai-jie/yueyu-shi-yong-xian-zhi-wen-ti.md)

***

### 使用請求 ID

如果可用， **請求 ID** 是最有助於疑難排解的識別碼。

若要調查失敗的請求：

1. 開啟 **用量記錄**.

<figure><img src="/files/032362f2567318ac67465257328b78f6fb66a850" alt=""><figcaption></figcaption></figure>

2. 找出相關請求。
3. 請檢查：
   * 請求 ID
   * 模型
   * 狀態
   * 錯誤訊息
   * 費用
4. 在聯絡支援之前，請先儲存這些資訊。

提供請求 ID 可協助支援更有效率地找到請求詳細資訊。

***

### 何時聯絡支援

如果符合以下情況，請聯絡支援：

* 同一請求在驗證後仍持續失敗
* 您收到未預期的伺服器錯誤
* 付款或用量記錄看起來不正確
* 無法從用量記錄解釋請求狀態

請提供：

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

請勿提供：

* 完整 API Token
* 帳戶密碼
* 付款憑證

> 🔐 切勿向支援提供完整的 API Token。

***

### 🚀 後續步驟

請繼續參閱：

* [**API Token 與驗證問題**](/documentation/zh-tw/yi-nan-pai-jie/api-quan-zhang-yu-yan-zheng-wen-ti.md)
* [**模型與請求錯誤**](/documentation/zh-tw/yi-nan-pai-jie/mo-xing-yu-qing-qiu-cuo-wu.md)
* [**餘額與用量限制問題**](/documentation/zh-tw/yi-nan-pai-jie/yueyu-shi-yong-xian-zhi-wen-ti.md)
* [**逾時與連線問題**](/documentation/zh-tw/yi-nan-pai-jie/yu-shi-yu-lian-xian-wen-ti.md)
* [**用量記錄與費用**](/documentation/zh-tw/api-shi-yong/shi-yong-ji-lu-yu-fei-yong.md)