錯誤處理 - 黑猪AI 开发者文档

接入時需要區分兩類錯誤：建立或查詢請求立即失敗，以及任務已建立後進入 failed 狀態。

HTTP 錯誤

狀態碼	含義	建議
`400`	請求體、模型或引數不符合要求	修正引數後再提交
`401`	Token 缺失、無效或已停用	檢查認證請求頭與 Token 狀態
`402`	可用額度不足	補充餘額或選擇成本更低的任務
`404`	任務不存在或無權訪問	檢查任務 ID 和建立任務的賬戶
`429`	請求頻率或活躍查詢過多	使用指數退避並降低併發
`500`	平臺內部錯誤	記錄請求時間並稍後重試
`502` / `503`	模型服務超時、繁忙或暫不可用	等待後有限重試，持續發生時聯絡支援

任務失敗

查詢任務返回 failed 時，響應中會包含錯誤物件：

{
  "id": "task_xxxxxxxxxx",
  "object": "video",
  "status": "failed",
  "progress": 0,
  "error": {
    "code": "video_generation_failed",
    "message": "任务失败原因"
  }
}

任務失敗後應停止輪詢。是否重試取決於錯誤原因：

引數或素材錯誤：修正請求後建立新任務。
內容稽核拒絕：調整提示詞或素材後再試。
臨時超時或服務繁忙：等待一段時間後有限重試。
未知錯誤：保留任務 ID 與完整錯誤響應並聯系技術支援。

重試原則

第 1 次重试：等待 5 秒
第 2 次重试：等待 15 秒
第 3 次重试：等待 30 秒

僅對網路錯誤、429、502 和 503 等臨時故障執行有限重試。不要自動無限重試，也不要對引數錯誤原樣重試。

聯絡支援時提供發生時間、模型名稱、任務 ID、HTTP 狀態碼和錯誤訊息即可。請隱藏 API Token、參考素材中的敏感資訊和個人資料。