當你將 CometAPI 錯誤處理區分為請求結構問題、驗證問題、路徑錯誤與可重試的平台失敗時，會更容易處理。結合 HTTP 狀態、error.code 與 error.message，即可判斷應該修正請求，還是進行重試。
快速分診
錯誤封裝
許多 CometAPI 失敗會使用如下的錯誤主體：
有些回應會將 code 留空。當狀態為 500 時，請將 error.code 與 error.message 視為判斷依據。
400 Bad Request
400 通常表示請求主體在請求能被正常處理之前，未通過驗證。
常見原因：
- 缺少必要欄位，例如
model
- JSON 結構無效
- 傳送了類型錯誤的欄位
- 重用了所選 endpoint 不接受的供應商特定參數
請從最小的已知正常請求開始，然後再逐一加回可選欄位。將 payload 與 API 參考文件中的 endpoint 結構進行比對。
使用如下的最小請求：
將 your-model-id 替換為 CometAPI Models page 中任何目前可用的 model ID。
不要假設每個格式錯誤的聊天請求都會回傳 400。缺少必要聊天欄位（例如 messages）時，也可能以 500 搭配 error.code: invalid_request 的形式出現。
500 Internal Server Error
大多數 500 回應表示平台或供應商失敗。對於聊天補全，一些格式錯誤的請求也可能以 500 的形式出現，同時仍攜帶 error.code: invalid_request。
其中一個例子是省略 messages 的請求：
如果 500 回應包含 error.code: invalid_request，請將其視為請求問題：
- 修正請求主體。
- 將 payload 與 endpoint 結構進行比對。
- 僅在修正 payload 之後再重試。
如果 500 回應未指向無效請求，請保留 request id 並使用退避機制。
401 Invalid Token
Token 失敗通常會長這樣：
請檢查：
- 標頭必須完全是
Authorization: Bearer $COMETAPI_KEY。
- 確認你的應用程式沒有從
.env、shell 歷史紀錄或已部署的 secret store 載入舊的 key。
- 如果同一個請求中某個 key 失敗而另一個 key 可用，請將其視為 token 問題，而不是 endpoint 問題。
403 Forbidden
403 最常見的是以下其中一種情況：
- 請求被平台端規則阻擋，例如 WAF 過濾
- token 或路由無權使用所請求的 model 或請求格式
- 所選 model 拒絕你傳入的某個進階參數
首先該做的事：
- 先用非常簡單的文字請求，對一個已知正常的 model 重試。
- 移除進階欄位與 provider 專屬參數，之後再逐步加回來。
- 如果回應中包含 request id，聯絡支援前請先保留它。
如果訊息提到像是 group 或 channel 這類內部術語，請將它們視為路由細節，而不是從用戶端開始診斷的第一優先。實際上的修復方式仍然是先驗證 token、model 與請求格式。
錯誤的 base URL 或錯誤的路徑
在 Comet 上，路徑錯誤可能會表現為：
- 重新導向
- 如果你的 client 會跟隨重新導向，則收到非 JSON 的 HTML 回應
- 你的 SDK 內部發生解析錯誤
- 請求始終無法乾淨地到達 API 層
請精確使用這個 base URL：
建議檢查：
- 確認 base URL 包含
/v1。
- 確認 endpoint 路徑與文件完全一致。
- 在偵錯路徑問題時，停用自動跟隨重新導向。
413 Request Entity Too Large
如果你看到 413，請先將它視為請求大小問題。常見原因包括：
- 大型 base64 負載
- 內嵌的超大圖片或音訊
- 非常大的 multipart 或 JSON 內容
該怎麼做：
- 減少或壓縮附加內容。
- 將大型工作拆分成較小的請求。
- 不要假設只有純文字長度才會造成這個問題。
429 Too Many Requests
請將 429 視為可重試：
- 使用帶有 jitter 的指數退避。
- 降低突發並發數。
- 保持請求記錄啟用，這樣你就能看出是哪個路由與 model 最先達到飽和。
如需可重複使用的重試模式，請參閱聊天補全中的 backoff 範例。
503、504 與 524
這些狀態碼屬於伺服器端或逾時類型失敗。
實務指引：
503：路由或 provider 服務暫時不可用504 與 524：平台、邊緣層或 provider 服務之間的逾時類型失敗
該怎麼做：
- 使用退避策略重試。
- 保留
request id、endpoint、model 與時間戳記。
- 如果相同失敗在多次重試後仍持續發生，請帶著這些資訊聯絡支援。
聯絡支援之前
請先蒐集以下詳細資訊：
- HTTP 方法
- Endpoint 路徑
- Model ID
- 已去識別化的 request body JSON（對大多數 API 呼叫而言，這是最有幫助的一項資訊）
- 如果失敗的 request 使用了查詢參數，請一併提供
- 如果你的用戶端有擷取到，請提供完整的 response body
- 完整的 HTTP 狀態碼
- 確切的
error.message
- 任何
request id
- 大約的時間戳記
- 相同的 request 是否可在另一個 model 或另一個 token 上正常運作
如果失敗的路由接受的是 檔案上傳（影像編輯、音訊上傳、影片生成等），而不是一般的 JSON body，請提供對應的已提交 payload：
- 你隨檔案一併送出的欄位名稱與文字值
- 檔名、檔案類型，以及大約的檔案大小
- 檔案是直接上傳、以 URL 參照，還是以 base64 內嵌
重現 bug 最有效的方式，是提供確切且已去識別化的 request payload。對大多數 API 呼叫來說，這表示 原始 request body JSON。對檔案上傳路由來說，則表示欄位清單加上檔案中繼資料。
