跳至主要内容

錯誤修復

依錯誤現象與 HTTP 狀態碼定位原因，先完成最小驗證，再逐步恢復請求。

401 未驗證​

  • 現象： 請求通常會回傳 401 未驗證，用戶端也可能只顯示「請求失敗」。
  • 原因： Key 遺漏、失效、複製不完整，或驗證標頭不符合目前協定。
  • 自查：
    1. 記錄完整 HTTP 狀態、請求路徑與發生時間。
    2. 重新複製 Key，確認沒有空白、換行且仍處於啟用狀態。
    3. 依協定對照 Base URL、模型與認證標頭，修正後再用最小 curl 驗證。
  • 處理： 重新從金鑰頁複製 Key，移除前後空白，並核對 Bearer、x-api-key 或 x-goog-api-key。
  • 驗證： 修復後先送出一則短文字請求；收到正常 JSON 與內容後再恢復原本參數。

403 無權限​

  • 現象： 請求通常會回傳 403 無權限，用戶端也可能只顯示「請求失敗」。
  • 原因： 目前 Key、帳戶狀態或模型存取範圍不允許此請求。
  • 自查：
    1. 記錄完整 HTTP 狀態、請求路徑與發生時間。
    2. 重新複製 Key，確認沒有空白、換行且仍處於啟用狀態。
    3. 依協定對照 Base URL、模型與認證標頭，修正後再用最小 curl 驗證。
  • 處理： 確認 Key 仍可用，並在模型與價格頁重新選擇可存取的模型。
  • 驗證： 修復後先送出一則短文字請求；收到正常 JSON 與內容後再恢復原本參數。

404 找不到​

  • 現象： 請求通常會回傳 404 找不到，用戶端也可能只顯示「請求失敗」。
  • 原因： Base URL、協定路徑或 HTTP 方法不符，用戶端也可能重複附加 /v1。
  • 自查：
    1. 記錄完整 HTTP 狀態、請求路徑與發生時間。
    2. 重新複製 Key，確認沒有空白、換行且仍處於啟用狀態。
    3. 依協定對照 Base URL、模型與認證標頭，修正後再用最小 curl 驗證。
  • 處理： 對照協定頁檢查完整路徑與方法；Base URL 只填入教學指定層級。
  • 驗證： 修復後先送出一則短文字請求；收到正常 JSON 與內容後再恢復原本參數。

429 請求過多​

  • 現象： 請求通常會回傳 429 請求過多，用戶端也可能只顯示「請求失敗」。
  • 原因： 短時間內請求太密集，或目前可用額度不足。
  • 自查：
    1. 記錄完整 HTTP 狀態、請求路徑與發生時間。
    2. 重新複製 Key，確認沒有空白、換行且仍處於啟用狀態。
    3. 依協定對照 Base URL、模型與認證標頭，修正後再用最小 curl 驗證。
  • 處理： 降低並行數，依遞增間隔重試，並在主站確認帳戶狀態。
  • 驗證： 修復後先送出一則短文字請求；收到正常 JSON 與內容後再恢復原本參數。

5xx 服務錯誤​

  • 現象： 請求通常會回傳 5xx 服務錯誤，用戶端也可能只顯示「請求失敗」。
  • 原因： 上游或閘道暫時無法完成請求。
  • 自查：
    1. 記錄完整 HTTP 狀態、請求路徑與發生時間。
    2. 重新複製 Key，確認沒有空白、換行且仍處於啟用狀態。
    3. 依協定對照 Base URL、模型與認證標頭，修正後再用最小 curl 驗證。
  • 處理： 保留請求時間與狀態碼，稍後重試；持續失敗時先用 curl 最小請求排除用戶端設定。
  • 驗證： 修復後先送出一則短文字請求；收到正常 JSON 與內容後再恢復原本參數。

網路中斷​

  • 現象： 請求通常會回傳 網路中斷，用戶端也可能只顯示「請求失敗」。
  • 原因： 本機網路、代理或長連線在回應完成前中斷。
  • 自查：
    1. 記錄完整 HTTP 狀態、請求路徑與發生時間。
    2. 重新複製 Key，確認沒有空白、換行且仍處於啟用狀態。
    3. 依協定對照 Base URL、模型與認證標頭，修正後再用最小 curl 驗證。
  • 處理： 確認網域可存取；串流請求使用退避重連，非冪等操作不要自動重複提交。
  • 驗證： 修復後先送出一則短文字請求；收到正常 JSON 與內容後再恢復原本參數。

建議排查順序​

  1. 先記錄完整錯誤：HTTP 狀態碼、請求路徑、用戶端名稱與發生時間。
  2. 用快速開始頁的最小 curl 請求重現，確認問題來自 Key、模型、位址或用戶端。
  3. 一次只修改一個變數；修復後先驗證短文字請求，再恢復串流、工具呼叫或媒體參數。

仍未恢復​

保留發生時間、協定、HTTP 方法、路徑、狀態碼與已遮蔽敏感內容的回應片段。不要附上完整 Key。

影片生成故障定位​

先判斷提交前、PopGo解析、服務接受、輪詢或下載階段。保留具体錯誤，不能只憑500或服務無紀錄歸因。

階段處理
first-frame requires exactly one / first-last-frame requires both選模式，首幀一張或兩個不同槽位，檢查連線及真實素材數
reference-audio requires at least one / audio not supported確認音訊能力與該模式掛載許可，提供音訊；generate_audio不授予輸入權限
unsupported protocol: data / invalid sourceURL限定型號改用允許的公開來源；本機標籤不會發布檔案
長期0% / completed下載失敗查原id並留時間準備內容，不用重新建立來消除等待
成功但忽略素材先查欄位與可讀性，再驗成片；HTTP200不足以驗收

HTTP400通常需修正請求，500也可能來自解析或中介層，503常為暫無容量。先查脫敏細節。影片任務排錯有完整輪詢、費用及證據界線。