> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 處理錯誤代碼

> 使用本指南分類 CometAPI 錯誤回應，並針對常見的請求失敗採取重試或修正步驟。

當你將 CometAPI 錯誤處理區分為**請求結構問題**、**驗證問題**、**路徑錯誤**與**可重試的平台失敗**時，會更容易處理。結合 HTTP 狀態、`error.code` 與 `error.message`，即可判斷應該修正請求，還是進行重試。

## 快速分診

| Status                                   | 通常代表什麼                                                                          | 要重試嗎？ | 第一個動作                                               |
| ---------------------------------------- | ------------------------------------------------------------------------------- | ----- | --------------------------------------------------- |
| `400`                                    | 請求在正常處理之前，未通過請求驗證。                                                              | 否     | 驗證 `model`、`messages`、JSON 結構與欄位類型。                 |
| `401`                                    | API key 缺失、格式錯誤或無效。                                                             | 否     | 檢查 `Authorization: Bearer $COMETAPI_KEY`。           |
| `403`                                    | 存取遭到阻擋，或目前的請求不被允許。                                                              | 通常否   | 使用已知正常的請求重試，並先移除模型特定欄位。                             |
| Path mistake                             | base URL 錯誤或 endpoint 路徑錯誤。在 Comet 上，這可能顯示為 `301` 重新導向或 HTML，而不是乾淨的 JSON `404`。 | 否     | 精確使用 `https://api.cometapi.com/v1`，並在除錯時停用自動跟隨重新導向。 |
| `429`                                    | 速率限制或暫時性飽和。                                                                     | 是     | 使用帶有 jitter 的指數退避。                                  |
| `500` with `error.code: invalid_request` | 格式錯誤的請求透過伺服器狀態回應浮現。                                                             | 否     | 在重試前先修正請求主體。                                        |
| `500`, `503`, `504`, `524`               | 平台、供應商或逾時類型的失敗。                                                                 | 是     | 使用退避重試，並保留 request id。                              |

## 錯誤封裝

許多 CometAPI 失敗會使用如下的錯誤主體：

```json theme={null}
{
	"error": {
		"message": "...",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
```

有些回應會將 `code` 留空。當狀態為 `500` 時，請將 `error.code` 與 `error.message` 視為判斷依據。

## `400 Bad Request`

`400` 通常表示請求主體在請求能被正常處理之前，未通過驗證。

常見原因：

* 缺少必要欄位，例如 `model`
* JSON 結構無效
* 傳送了類型錯誤的欄位
* 重用了所選 endpoint 不接受的供應商特定參數

請從最小的已知正常請求開始，然後再逐一加回可選欄位。將 payload 與 API 參考文件中的 endpoint 結構進行比對。

使用如下的最小請求：

```json theme={null}
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
```

將 `your-model-id` 替換為 [CometAPI Models page](/zh-Hant/overview/models) 中任何目前可用的 model ID。

不要假設每個格式錯誤的聊天請求都會回傳 `400`。缺少必要聊天欄位（例如 `messages`）時，也可能以 `500` 搭配 `error.code: invalid_request` 的形式出現。

## `500 Internal Server Error`

大多數 `500` 回應表示平台或供應商失敗。對於聊天補全，一些格式錯誤的請求也可能以 `500` 的形式出現，同時仍攜帶 `error.code: invalid_request`。

其中一個例子是省略 `messages` 的請求：

```json theme={null}
{
	"error": {
		"message": "field messages is required (request id: ...)",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
```

如果 `500` 回應包含 `error.code: invalid_request`，請將其視為請求問題：

1. 修正請求主體。
2. 將 payload 與 endpoint 結構進行比對。
3. 僅在修正 payload 之後再重試。

如果 `500` 回應未指向無效請求，請保留 `request id` 並使用退避機制。

## `401 Invalid Token`

Token 失敗通常會長這樣：

```json theme={null}
{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}
```

請檢查：

1. 標頭必須完全是 `Authorization: Bearer $COMETAPI_KEY`。
2. 確認你的應用程式沒有從 `.env`、shell 歷史紀錄或已部署的 secret store 載入舊的 key。
3. 如果同一個請求中某個 key 失敗而另一個 key 可用，請將其視為 token 問題，而不是 endpoint 問題。

## `403 Forbidden`

`403` 最常見的是以下其中一種情況：

* 請求被平台端規則阻擋，例如 WAF 過濾
* token 或路由無權使用所請求的 model 或請求格式
* 所選 model 拒絕你傳入的某個進階參數

首先該做的事：

1. 先用非常簡單的文字請求，對一個已知正常的 model 重試。
2. 移除進階欄位與 provider 專屬參數，之後再逐步加回來。
3. 如果回應中包含 request id，聯絡支援前請先保留它。

<Warning>
  如果訊息提到像是 `group` 或 `channel` 這類內部術語，請將它們視為路由細節，而不是從用戶端開始診斷的第一優先。實際上的修復方式仍然是先驗證 token、model 與請求格式。
</Warning>

## 錯誤的 base URL 或錯誤的路徑

在 Comet 上，路徑錯誤可能會表現為：

* 重新導向
* 如果你的 client 會跟隨重新導向，則收到非 JSON 的 HTML 回應
* 你的 SDK 內部發生解析錯誤
* 請求始終無法乾淨地到達 API 層

請精確使用這個 base URL：

```text theme={null}
https://api.cometapi.com/v1
```

建議檢查：

1. 確認 base URL 包含 `/v1`。
2. 確認 endpoint 路徑與文件完全一致。
3. 在偵錯路徑問題時，停用自動跟隨重新導向。

## `413 Request Entity Too Large`

如果你看到 `413`，請先將它視為**請求大小**問題。常見原因包括：

* 大型 base64 負載
* 內嵌的超大圖片或音訊
* 非常大的 multipart 或 JSON 內容

該怎麼做：

1. 減少或壓縮附加內容。
2. 將大型工作拆分成較小的請求。
3. 不要假設只有純文字長度才會造成這個問題。

## `429 Too Many Requests`

請將 `429` 視為可重試：

1. 使用帶有 jitter 的指數退避。
2. 降低突發並發數。
3. 保持請求記錄啟用，這樣你就能看出是哪個路由與 model 最先達到飽和。

如需可重複使用的重試模式，請參閱[聊天補全](/api/text/chat)中的 backoff 範例。

## `503`、`504` 與 `524`

這些狀態碼屬於**伺服器端或逾時類型失敗**。

實務指引：

* `503`：路由或 provider 服務暫時不可用
* `504` 與 `524`：平台、邊緣層或 provider 服務之間的逾時類型失敗

該怎麼做：

1. 使用退避策略重試。
2. 保留 `request id`、endpoint、model 與時間戳記。
3. 如果相同失敗在多次重試後仍持續發生，請帶著這些資訊聯絡支援。

## 聯絡支援之前

請先蒐集以下詳細資訊：

* HTTP 方法
* Endpoint 路徑
* Model ID
* **已去識別化的 request body JSON**（對大多數 API 呼叫而言，這是最有幫助的一項資訊）
* 如果失敗的 request 使用了查詢參數，請一併提供
* 如果你的用戶端有擷取到，請提供完整的 response body
* 完整的 HTTP 狀態碼
* 確切的 `error.message`
* 任何 `request id`
* 大約的時間戳記
* 相同的 request 是否可在另一個 model 或另一個 token 上正常運作

如果失敗的路由接受的是 **檔案上傳**（影像編輯、音訊上傳、影片生成等），而不是一般的 JSON body，請提供對應的已提交 payload：

* 你隨檔案一併送出的欄位名稱與文字值
* 檔名、檔案類型，以及大約的檔案大小
* 檔案是直接上傳、以 URL 參照，還是以 base64 內嵌

<Warning>
  重現 bug 最有效的方式，是提供確切且已去識別化的 request payload。對大多數 API 呼叫來說，這表示 **原始 request body JSON**。對檔案上傳路由來說，則表示欄位清單加上檔案中繼資料。
</Warning>

這能大幅縮短支援處理時間。