跳轉到主要內容

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 錯誤處理區分為請求格式問題、驗證問題、路徑錯誤與可重試的平台故障時，處理會最簡單。請結合 HTTP 狀態碼、error.code 與 error.message 來判斷應修正請求，還是重試它。

​
快速分流

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

​
錯誤封裝

許多 CometAPI 失敗回應會使用如下的錯誤主體： 
{
	"error": {
		"message": "...",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
有些回應會讓 code 保持空白。當狀態碼是 500 時，請將 error.code 與 error.message 視為判斷依據。

​
400 Bad Request

400 通常表示請求主體在請求可被正常處理前就未通過驗證。 常見原因：
  • 缺少必要欄位，例如 model
  • JSON 結構無效
  • 傳送了型別錯誤的欄位
  • 重複使用了所選 endpoint 不接受的 provider 專屬參數
請從最小且已知可正常運作的請求開始，再逐一把選填欄位加回來。將 payload 與 API 參考文件中的 endpoint schema 進行比對。 可使用如下的最小請求： 
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
將 your-model-id 替換為來自 CometAPI Models page 的任何目前 model ID。 不要假設每個格式錯誤的聊天請求都會回傳 400。缺少必要的聊天欄位（例如 messages）也可能以 500 與 error.code: invalid_request 的形式出現。

​
500 Internal Server Error

大多數 500 回應表示平台或 provider 故障。對於聊天補全，某些格式錯誤的請求也可能以 500 的形式出現，同時仍攜帶 error.code: invalid_request。 其中一個例子是省略 messages 的請求： 
{
	"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 schema 進行比對。
  3. 僅在修正 payload 後才重試。
如果 500 回應未指出是無效請求，請保留 request id 並使用退避。

​
401 Invalid Token

token 失敗通常會像這樣： 
{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}
請檢查：
  1. 標頭必須完全是 Authorization: Bearer <COMETAPI_KEY>。
  2. 確認你的應用程式沒有從 .env、shell 歷史紀錄或已部署的 secret store 載入舊金鑰。
  3. 如果同一個請求中某個金鑰失敗而另一個金鑰可用，請將其視為 token 問題，而不是 endpoint 問題。

​
403 Forbidden

403 最常見的是以下其中一種情況：
  • 請求被平台端規則阻擋，例如 WAF 過濾
  • token 或路由未被允許使用所請求的 model 或請求形態
  • 所選 model 拒絕了你傳入的某個進階參數
首先要做的事：
  1. 針對一個已知可用的 model，以非常簡單的文字請求重試。
  2. 移除進階欄位與 provider 專屬參數，然後再逐步加回去。
  3. 如果回應中包含 request id，請在聯絡支援前先保留它。
如果訊息中提到像 group 或 channel 這類內部術語，請將它們視為路由細節，而不是從用戶端角度優先診斷的對象。實際上的修復方式仍然是先驗證 token、model 與請求形態。

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

在 Comet 上，路徑錯誤可能會表現為：
  • 重新導向
  • 如果你的用戶端會跟隨重新導向，則會收到非 JSON 的 HTML 回應
  • SDK 內部發生解析錯誤
  • 請求始終無法乾淨地到達 API 層
請精確使用這個 base URL： 
https://api.cometapi.com/v1
建議檢查：
  1. 確認 base URL 包含 /v1。
  2. 確認 endpoint 路徑與文件完全一致。
  3. 在除錯路徑問題時，停用自動跟隨重新導向。

​
413 Request Entity Too Large

如果你看到 413，請先將它視為請求大小問題。常見可疑原因包括：
  • 大型 base64 payload
  • 內嵌的超大圖片或音訊
  • 非常大的 multipart 或 JSON 請求主體
處理方式：
  1. 減少或壓縮附加內容。
  2. 將大型工作拆分成較小的請求。
  3. 不要假設只有純文字長度才是原因。

​
429 Too Many Requests

請將 429 視為可重試：
  1. 使用帶有抖動的指數退避。
  2. 降低突發並發量。
  3. 保持請求日誌開啟，這樣你才能看出是哪些路由與 model 先達到飽和。
若要使用可重複利用的重試模式，請參考聊天補全中的 backoff 範例。

​
503、504 與 524

這些狀態碼屬於伺服器端或逾時類型失敗。 實務指引：
  • 503：路由或 provider 服務暫時無法使用
  • 504 與 524：平台、邊緣或 provider 服務之間的逾時類型失敗
處理方式：
  1. 使用 backoff 重試。
  2. 保留 request id、endpoint、model 與時間戳記。
  3. 如果相同失敗在多次重試後仍持續發生，請帶著這些背景資訊聯絡支援。

​
聯絡支援前

請先蒐集以下詳細資訊：
  • HTTP method
  • Endpoint path
  • Model ID
  • 已去除敏感資訊的請求 body JSON（對大多數 API 呼叫來說，這是最有幫助的單一項目）
  • 如果失敗的請求有使用 query parameters，請一併提供
  • 如果你的用戶端有擷取到，請提供完整的 response body
  • 完整的 HTTP status
  • 精確的 error.message
  • 任何 request id
  • 約略的時間戳記
  • 相同的請求是否可在另一個 model 或另一個 token 上正常運作
如果失敗的路由接受的是 檔案上傳（影像編輯、音訊上傳、影片生成等），而不是一般的 JSON body，請提供等效的送出 payload：
  • 你與檔案一同送出的欄位名稱與文字值
  • 檔名、檔案類型，以及大約的檔案大小
  • 檔案是直接上傳、以 URL 引用，還是以 base64 內嵌
重現 bug 最有效的方式，是提供精確且已去除敏感資訊的請求 payload。對大多數 API 呼叫而言，這表示 原始 request body JSON。對檔案上傳路由而言，則表示欄位清單加上檔案中繼資料。
這能大幅縮短支援處理所需的時間。