跳轉到主要內容
當你將 請求問題、驗證問題 與 可重試的平台問題 分開處理時，CometAPI 的錯誤處理會變得最簡單。這個頁面是 CometAPI 的正式錯誤指南，重點放在你可以先從客戶端驗證的項目。
本指南是根據目前 CometAPI API 的實際測試結果整理而成。我們已直接驗證 400、401 與路徑/base URL 失敗的情況。我們沒有在受控測試中重現 413、429、500、503、504 或 524，因此針對這些狀態碼的建議刻意採取較保守的寫法。

​
快速分流

Status通常代表什麼Retry?第一個動作
400請求在成功路由之前就未通過驗證。否驗證 model、messages、JSON 結構與欄位型別。
401API key 遺失、格式錯誤或無效。否檢查 Authorization: Bearer <COMETAPI_KEY>。
403存取遭到阻擋，或目前請求不被允許。通常否使用已知可正常運作的請求重試，並先移除模型專用欄位。
路徑錯誤base URL 或 endpoint 路徑錯誤。在 Comet 上，這可能會顯示為 301 重新導向或 HTML，而不是乾淨的 JSON 404。否務必使用 https://api.cometapi.com/v1，並在除錯時停用自動跟隨重新導向。
429速率限制或暫時性飽和。是使用帶抖動的指數退避。
500, 503, 504, 524平台或逾時類失敗。是使用退避重試，並保留 request id。

​
錯誤封裝格式

CometAPI 目前回傳的 JSON 錯誤封裝格式如下： 
{
	"error": {
		"code": "",
		"message": "...",
		"type": "comet_api_error"
	}
}
許多實際錯誤訊息也會在 error.message 中包含 request id。當你需要支援時，請保存這個值。

​
400 Bad Request

當省略 model 時，我們從實際 API 觀察到的結果如下： 
{
	"error": {
		"code": "",
		"message": "model name is required (request id: ...)",
		"type": "comet_api_error"
	}
}
在實務上，400 通常表示請求本文在平台能將其路由至模型提供者之前，就已經驗證失敗。 常見原因：
  • 缺少必要欄位，例如 model 或 messages
  • JSON 結構無效
  • 傳送了型別錯誤的欄位
  • 重複使用了所選 endpoint 不接受的供應商專屬參數
該怎麼做：
  1. 從最小且已知可正常運作的請求開始。
  2. 將選用欄位逐一加回。
  3. 將請求本文與 API 參考文件中的 endpoint 結構描述進行比對。
最小可正常運作範例： 
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
請將 your-model-id 替換為 CometAPI Models page 中目前可用的任一 model ID。

​
401 Invalid Token

使用無效 key 時，我們從實際 API 觀察到的結果如下： 
{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}
需要檢查的事項：
  1. Header 必須完全是 Authorization: Bearer <COMETAPI_KEY>。
  2. 確認你的應用程式沒有從 .env、shell 歷史紀錄或已部署的 secret store 載入舊 key。
  3. 如果同一個請求中某個 key 失敗而另一個 key 可以正常運作，應將其視為 token 問題，而不是 endpoint 問題。

​
403 Forbidden

我們在有界測試中未重現穩定的 403，因此不要將單一舊版訊息範本視為完整情況。 在目前的 Comet 文件中，403 最常見於以下幾種情況：
  • 請求被平台端規則阻擋，例如 WAF 過濾
  • token 或 route 不被允許使用所請求的 model 或請求形式
  • 所選 model 拒絕你傳入的某個進階參數
首先該怎麼做：
  1. 使用已知正常的 model，發送非常簡單的文字請求再次嘗試。
  2. 移除進階欄位與 provider 專用參數，之後再逐步加回。
  3. 如果回應中包含 request id，請在聯絡支援前先保留它。
如果訊息中提到像是 group 或 channel 這類內部術語，請將它們視為路由細節，而不是從用戶端開始診斷的首要事項。實務上的修正方式仍然是先驗證 token、model 和請求形式。

​
錯誤的 Base URL 或錯誤的路徑

這是舊版頁面最不準確的部分。 根據目前 Comet 端點的即時檢查：
  • 對 https://api.cometapi.com/chat/completions 發送請求時，會回傳重新導向至 https://www.cometapi.com/chat/completions 的 301
  • 對假的 API 路由發送請求，例如 https://api.cometapi.com/v1/not-a-real-endpoint，也會回傳重新導向至 https://www.cometapi.com/v1/not-a-real-endpoint 的 301
這表示路徑錯誤可能會呈現為：
  • 重新導向
  • 如果你的 client 會跟隨重新導向，則會收到非 JSON 的 HTML 回應
  • SDK 內部出現解析錯誤
  • 請求根本沒有乾淨地到達 API 層
請務必精確使用以下 base URL： 
https://api.cometapi.com/v1
建議檢查項目：
  1. 確認 base URL 包含 /v1。
  2. 確認 endpoint 路徑與文件完全一致。
  3. 在除錯路徑問題時，停用自動跟隨重新導向。

​
413 Request Entity Too Large

即使使用超大的 8 MiB JSON 請求主體，我們在有界測試中仍未重現 413，因此舊版將原因解釋為 prompt 太長，這個說法過於狹隘。 如果你確實看到 413，請先將它視為請求大小問題。常見可疑原因包括：
  • 大型 base64 負載
  • 內嵌的超大圖片或音訊
  • 非常大的 multipart 或 JSON 主體
該怎麼做：
  1. 縮小或壓縮附加內容。
  2. 將大型工作拆分成較小的請求。
  3. 不要假設只有純文字長度才是原因。

​
429 Too Many Requests

我們在對 24 個平行 GET /v1/models 請求進行有界並發探測時，未重現 429，因此實際門檻顯然取決於 route、model 與當前平台狀態。 請將 429 視為可重試的錯誤：
  1. 使用帶有抖動（jitter）的指數退避。
  2. 降低突發並發數。
  3. 保持請求記錄開啟，以便查看是哪個 route 和 model 最先達到飽和。
如需可重複使用的重試模式，請參閱聊天補全中的 backoff 範例。

​
500, 503, 504, And 524

我們在有界測試中未重現這些狀態碼。它們應被記錄為伺服器端或逾時類型故障，而不是使用者錯誤。 實務指引：
  • 500：平台內部或 provider 端故障
  • 503：route 或 provider 服務暫時不可用
  • 504 和 524：平台、邊緣節點或 provider 服務之間的逾時類型故障
該怎麼做：
  1. 使用退避策略重試。
  2. 保留 request id、endpoint、model 與時間戳記。
  3. 如果相同故障在多次重試後仍持續出現，請帶著這些背景資訊聯絡支援。

​
聯絡支援前

請先蒐集以下詳細資訊：
  • HTTP 方法
  • Endpoint 路徑
  • 模型名稱
  • 已淨化的請求本文 JSON（對大多數 API 呼叫而言，這是最有幫助的一項資訊）
  • 若失敗的請求有使用查詢參數，請提供查詢參數
  • 若你的用戶端有擷取到，請提供完整的回應本文
  • 完整的 HTTP 狀態碼
  • 精確的 error.message
  • 任何 request id
  • 約略時間戳記
  • 相同請求是否能在另一個模型或另一個 token 下正常運作
如果失敗的路由接受的是檔案上傳（影像編輯、音訊上傳、影片生成等），而不是一般的 JSON 本文，請提供對應的提交內容：
  • 你隨檔案一同送出的欄位名稱與文字值
  • 檔案名稱、檔案類型與約略檔案大小
  • 檔案是直接上傳、以 URL 引用，還是以 base64 內嵌
重現 bug 最快的方法，就是提供精確且已淨化的請求 payload。對大多數 API 呼叫來說，這表示 原始請求本文 JSON。對檔案上傳路由而言，則表示欄位清單加上檔案中繼資料。
這能大幅縮短支援處理時間。