錯誤碼與排查

排查時請先記錄：HTTP 狀態碼、平台傳回的請求識別碼、模型 ID、任務 ID、素材 ID 與原始錯誤碼。

不要記錄 API Key、真人工作階段 Token 或完整的素材下載位址；提交給平台支援前請先去識別化。

HTTP 狀態含義

404 有三種成因，不要一律當成「ID 寫錯了」

這是排查時最容易誤判的一點：

收到 404 時，請先確認路徑與方法是否相符，再懷疑 ID。

查不到影片任務時傳回 400，不是 404

這一點與其他介面不一致，需要特別注意：

影片任務查詢會以 400 + 頂層 {code, message, data} 結構傳回， 既不是 404，也不是下文所述的 error 物件結構。

錯誤回應有三種結構

1. 模型 / 圖片 / 影片生成介面 —— error 物件

失敗時傳回 HTTP 非 2xx，並附帶一個 error 物件：

{
  "error": {
    "code": "invalid_parameter",
    "message": "请求参数不符合所选模型要求",
    "type": "invalid_request_error",
    "param": "size"
  }
}

code 可能是空字串。 實測：驗證失敗與請求內容 JSON 無法解析時，code 都是 ""。 不要用 code 是否為空來判斷「是不是錯誤」，應以 HTTP 狀態碼為準，並優先讀取 message。

type 不是穩定的分類欄位。 需要分類時請讀取 code，不要依賴 type 的取值。

2. 素材庫介面 —— 頂層 code

傳回 HTTP 非 2xx，code 與 HTTP 狀態一致：

{ "code": 404, "data": null, "msg": "素材不存在或无权访问" }

3. 影片任務查詢 —— 頂層 code 字串

{ "code": "task_not_exist", "message": "task_not_exist", "data": null }

請注意這裡的 code 是字串 task_not_exist，不是數字。

request id：排查問題的關鍵識別碼

平台會把 request id 直接寫在 error.message 裡，不需要到 header 裡尋找：

"message": "Invalid token (request id: 202609221135501066578648268d9d6uXuM5QgH)"

一行指令即可取出：

curl -s "$LOCOPAL_BASE_URL/v1/models" \
  -H "Authorization: Bearer sk-invalid" \
  | grep -oE 'request id: [A-Za-z0-9]+'

提交工單時附上這個 request id，可以大幅縮短定位時間。

驗證失敗

API keys 缺少、錯誤或已失效時，所有介面都會傳回 HTTP 401 與：

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: ...)",
    "type": "new_api_error"
  }
}

請注意 code 是空字串——這正是上文提醒「不要依賴 code」的原因。

模型與生成錯誤

素材庫錯誤

素材審核未完成不是錯誤：查詢會傳回 200，status 為 Processing，繼續輪詢同一個素材 ID 即可。

推理模型輸出為空也不是 HTTP 錯誤：如果傳回 200、finish_reason 為 length，且 usage.completion_tokens_details.reasoning_tokens 已佔滿輸出上限，應提高輸出額度或改用非推理模型。

真人授權錯誤

限流與重試

• 429 表示請求過於頻繁，請依提示退避重試，不要並行重試；
• 素材狀態建議每 5～10 秒查詢一次，影片任務建議每 5～15 秒一次；
• 僅對 429 與短暫的 5xx 重試；400 / 401 / 403 / 404 請直接修正請求；
• 重試前先依任務 ID / 素材 ID 查詢，避免重複建立與重複計費。

快速自我檢查

1. Authorization 是否為 Bearer <API Key>，Key 是否仍在啟用狀態；
2. 請求網域是否為目前主控台指定的位址（預設 https://locopalai.com，海外模型可能為 https://us-api.locopalai.com）；
3. model 是否來自 /v1/models 的 data[].id；
4. 素材 status 是否已經是 Active；
5. 參考圖片 / 影片位址是否為公開網路可直接存取的 http(s) 位址，且不依賴 Cookie 或 Referer；
6. 同一個任務 / 素材是否重複提交過。

提交支援時請附上

• 請求時間與介面路徑；
• HTTP 狀態碼與完整回應內容（API Key 請打馬賽克）；
• 平台傳回的請求識別碼、任務 ID 或素材 ID；
• 涉及的模型 ID 與參數；
• 可重現的最小請求範例。