錯誤與偵錯

讀取完整回覆

若狀態表示失敗，移除機密後請保留 HTTP 狀態碼、標頭、錯誤本文與請求 ID。這些資訊可區分無效請求、存取遭拒與暫時性問題。

請勿只向使用者顯示原始服務回覆；應說明動作，同時保留診斷細節供操作人員使用。

curl --include --request POST https://cicora.ai/api/v1/chat/completions \
  --header "Authorization: Bearer $CICORA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"model":"openai/gpt-5.6-sol","messages":[]}'

區分失敗類型

• 4xx 通常表示需要修正金鑰、輸入資料或存取權。
• 遇到 429 時，必須遵守限制時間窗，並避免過於積極地重試。
• 遇到 5xx 與網路失敗時，應採用次數有上限、含指數退避與隨機抖動的重試機制。

安全重試

只重試暫時性失敗，且操作在產品中必須具有冪等性。進行生成時，請保留用戶端請求 ID，以免重複扣款或產生重複成品。

串流處理時，必須區分第一個增量前發生的錯誤，與已有部分輸出後中斷的情況；後者不能在未告知的情況下改用新回覆取代。