錯誤

當請求到達 API 圖層時，開啟 API 錯誤使用 JSON 回應主體。網路故障、CDN 故障和二進位回應中斷可能不會具有這種精確的形狀，因此您的用戶端應該處理結構化 API 錯誤和傳輸錯誤。

每個端點使用相同的承載身份驗證上下文：

Authorization: Bearer KITTA_API_KEY

{
  "code": "invalid_request",
  "message": "The request payload is invalid.",
  "requestId": "req_xxx"
}

狀態程式碼

記錄端點、HTTP 方法、狀態、code、requestId 和您自己的內部作業 ID。除非您的隱私權政策和支援工作流程明確允許，否則請勿記錄承載 API 金鑰、完整使用者文字或私人媒體 URL。

對於非同步端點，請在日誌中包含 API 任務 ID 和內部資料庫 ID。這使得在不創建重複工作的情況下協調重試成為可能。

並非每個錯誤都具有相同的計費意義。驗證失敗通常發生在媒體工作開始之前。接受任務後可能會發生處理失敗。對於使用者導向的計費問題，請將任務狀態與新讀取的設定檔進行比較，而不是僅從 HTTP 狀態推斷成本。

使用退避重試 429 和一些 500 回應。不要盲目重試400、401或402；這些需要請求、憑證或帳單變更。對於建立端點，請在重試任何後續操作之前保留傳回的 id。