エラーコードとトラブルシューティング

調査時はまず、HTTP ステータスコード、プラットフォームが返すリクエスト識別子、モデル ID、タスク ID、素材 ID、元のエラーコードを記録してください。

API Key、実在人物セッションの Token、完全な素材ダウンロードアドレスは記録しないでください。プラットフォームサポートに提出する前に機密情報をマスクしてください。

HTTP ステータスの意味

404 には 3 つの原因があり、一律に「ID の書き間違い」とみなさない

これは調査時にもっとも誤判定しやすい点です：

404 を受け取ったら、まずパスとメソッドが一致しているかを確認し、その後に ID を疑ってください。

動画タスクが見つからない場合は 404 ではなく 400 を返す

ここは他のエンドポイントと一致しないため、特に注意が必要です：

動画タスクの照会は 400 + トップレベルの {code, message, data} 構造で返され、 404 でも、後述する error オブジェクト構造でもありません。

エラーレスポンスには 3 種類の構造がある

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)"

1 行のコマンドで取り出せます：

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 秒に 1 回、動画タスクは 5～15 秒に 1 回の照会を推奨します。
• 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 とパラメータ
• 再現可能な最小のリクエスト例