-4XXX (VideoGateway エラー)

お知らせ

このドキュメントは機械翻訳で作成された下書きであり、現在レビュー中です。機械翻訳の特性上、一部の内容が不正確であったり、韓国語の原文と異なる場合があります。より正確な情報については、韓国語のドキュメントをご参照ください。

再生 URL リクエスト時に Kollus VideoGateway が返すエラーです。開発初期に最もよく遭遇するエラーですので、連携コードを確認してください。

---

-4001

• エラーコード: -4001
• タイプ: ERROR_INVALID_MEDIA_CONTENT_KEY
• 概要: メディアコンテンツキーが無効

原因

原因	説明
チャンネルに登録されていないコンテンツ	コンテンツがチャンネルに登録されていないため、メディアコンテンツキー（mckey）が存在しない場合です。
トランスコーディング未完了	動画をアップロードした後、該当コンテンツのトランスコーディングがまだ完了していない状態です。
チャンネルから削除されたコンテンツ	一度チャンネルから削除されたコンテンツの既存の mckey は即時失効します。再登録時には新しいキーが発行されます。
アップロードファイルキーの誤入力	ライブラリ識別子である upload_file_key をメディアコンテンツキー（mckey）の箇所に誤って入力した場合です。

診断

正常なコンテンツ提供ワークフローに従って連携プロセスが進行されたか確認してください。

• 正しいプロセス: アップロード → トランスコーディング完了 → チャンネル登録 → メディアコンテンツキー発行 → JWT 生成 → 再生

解決方法

Kollus VOD コンソールから有効なメディアコンテンツキーを直接コピーして使用してください。

• 確認方法: Kollus VOD コンソール > [チャンネル] > 対象チャンネルを選択 > 対象コンテンツのメディアコンテンツキーをコピー

---

-4002

• エラーコード: -4002
• タイプ: ERROR_INVALID_SECURITY_KEY
• 概要: JWT 署名に使用したセキュリティーキーが Kollus サーバーに登録された値と一致しない

診断

1. 使用中の JWT トークンの署名検証のために validate_player_jwt ツールを実行してください。
2. 結果メッセージの signature_verified フィールドの値が false と出力された場合、セキュリティーキーの不一致状態を意味します。

解決方法

1. Kollus VOD コンソール > [サービスアカウント] > [ユーザーキー] からセキュリティーキーをコピーしてください。
2. コピーしたセキュリティーキーの文字列に不要な前後の空白や改行文字が含まれないよう注意して、JWT トークンの Secret 値として設定してください。

---

-4003

• エラーコード: -4003
• タイプ: ERROR_INVALID_CHANNEL_KEY
• 概要: チャンネルキーが無効

診断および解決方法

1. Kollus VOD コンソール > [チャンネル] に移動し、連携しようとする対象チャンネルが正常に作成されているか確認してください。
2. 対象チャンネルのチャンネルキーとソースコード内の入力値が一致しているか確認してください。

---

-4004

• エラーコード: -4004
• タイプ: ERROR_INVALID_USER_KEY
• 概要: プレイヤー URL の custom_key パラメーター値がコンソールのユーザーキー（Custom Key）と一致しない

診断および解決方法

Kollus VOD コンソール > [サービスアカウント] > [ユーザーキー] で確認したユーザーキーとソースコード内の入力値が一致しているか確認してください。

---

-4007

• エラーコード: -4007
• タイプ: ERROR_INVALID_USER_KEY
• 概要: JWT 規格または署名エラー

原因

原因	説明
JWT フォーマットエラー	トークンが header.payload.signature 形式の 3 段階ドット（.）パート規格を満たしていない場合です。
署名アルゴリズムエラー	Kollus は HS256 暗号化アルゴリズムのみサポートしています。RS256 などの他のアルゴリズムを指定するとエラーが発生します。
Payload 必須フィールドの欠落	mc[].mckey 配列フィールドが欠落しているか、チャンネルのセキュリティポリシー上必須の cuid 値が提供されていない場合です。
Base64Url エンコーディングエラー	一般的な Base64 エンコーディング時に発生する +、/、= 文字が含まれて通信規格が破損した場合です。

診断

発行された JWT データの元の構造を確認します。

• 方法 A: 以下のシェルスクリプトを使用して Payload 構造をパースしてください。

echo "YOUR_JWT" | cut -d'.' -f2 | base64 -d 2>/dev/null | python3 -m json.tool

• 方法 B: validate_player_jwt ツールを使用して JWT 規格が正しいか確認してください。

解決方法

診断結果をもとに JWT 暗号化モジュールのアルゴリズムを HS256 に固定し、Base64URL エンコーディング規格でトークン生成ロジックを修正してください。

---

-4082

• エラーコード: -4082
• タイプ: ERROR_MISMATCH_USER_KEY
• 概要: JWT Payload の特定フィールドまたは custom_key パラメーターで渡されたユーザーキーがチャンネルに登録されたキーと一致しない

診断および解決方法

開発・運用環境ごとに異なるキーを使用している場合、ソースコード内で環境変数や設定キーの値が混在していないか確認してください。

---

-4083

• エラーコード: -4083
• タイプ: ERROR_ACCESS_WITHOUT_MEDIA_CONTENT_KEY
• 概要: メディアコンテンツキーの欠落（JWT Payload の mc 配列が空、または mckey フィールドがない）

診断および解決方法

• 誤った例（配列が空）

{ "cuid": "user1", "mc": [] }

• 正しい例

{ "cuid": "user1", "mc": [{ "mckey": "MEDIA_CONTENT_KEY" }] }

---

-4085

• エラーコード: -4085
• タイプ: ERROR_TOKEN_EXPIRED
• 概要: 再生トークンの失効（JWT Payload の expt 値の失効）

原因

原因	説明
expt 値が過去の時刻	失効時間パラメーターの計算ロジックが誤っており、現在時刻より以前のタイムスタンプが入力された場合です。
時間単位の混同	タイムスタンプの時間単位（秒またはミリ秒）を混同して誤って入力した場合です。（kollus://guidance/jwt-playback-expiry 参照）
サーバー間の時刻同期のずれ	JWT 発行サーバーと Kollus サーバー間のシステム時刻の差が許容範囲（±1 分）を超えた場合です。
期限切れトークンの再利用	クライアントが失効した以前の JWT を再利用した場合です。

診断

validate_player_jwt ツールの expiry.expired フィールドの値を照会して、現在時刻基準で失効処理されているか確認してください。