Skip to main content

-4XXX (Video Gateway Error)

Notice

This document is a machine-translated draft and is currently undergoing review. Some content may be inaccurate or differ from the original Korean version. For the most precise information, refer to the Korean documentation.

These are errors returned by the Kollus Video Gateway when requesting a playback URL. Since these are the most commonly encountered errors during the early stages of development, review your integration code carefully.

-4001​

  • Error code: -4001
  • Type: ERROR_INVALID_MEDIA_CONTENT_KEY
  • Summary: The media content key is invalid

Cause​

CauseDescription
Content not registered to a channelThe content has not been registered to a channel, so the media content key (mckey) does not exist.
Transcoding not completeAfter uploading a video, the transcoding for that content has not yet finished.
Content removed from a channelAn existing mckey for content that has been removed from a channel expires immediately. A new key is issued upon re-registration.
Incorrect upload file key enteredThe upload_file_key, which is a library identifier, has been incorrectly entered in place of the media content key (mckey).

Diagnosis​

Verify that the integration process has followed the standard content delivery workflow.

  • Correct process: Upload → Transcoding complete → Register to channel → Media content key issued → Generate JWT → Playback

Solution​

Copy a valid media content key directly from the Kollus VOD console and use it.

  • Where to find: Kollus VOD console > [Channel] > Select target channel > Copy the media content key for the target content

-4002​

  • Error code: -4002
  • Type: ERROR_INVALID_SECURITY_KEY
  • Summary: The security key used to sign the JWT does not match the value registered on the Kollus server

Diagnosis​

  1. Run the validate_player_jwt tool to verify the signature of the JWT token in use.
  2. If the signature_verified field in the result shows false, it indicates a security key mismatch.

Solution​

  1. Copy the security key from Kollus VOD console > [Service account] > [Custom key].
  2. Set the copied security key string as the Secret value for the JWT token, making sure it does not contain any unnecessary leading/trailing spaces or newline characters.

-4003​

  • Error code: -4003
  • Type: ERROR_INVALID_CHANNEL_KEY
  • Summary: The channel key is invalid

Diagnosis and solution​

  1. Go to Kollus VOD console > [Channel] and verify that the target channel you want to integrate with has been created properly.
  2. Confirm that the channel key of the target channel matches the value entered in your source code.

-4004​

  • Error code: -4004
  • Type: ERROR_INVALID_USER_KEY
  • Summary: The custom_key parameter value in the player URL does not match the custom key in the console

Diagnosis and solution​

Confirm that the custom key retrieved from Kollus VOD console > [Service account] > [Custom key] matches the value entered in your source code.

-4007​

  • Error code: -4007
  • Type: ERROR_INVALID_USER_KEY
  • Summary: JWT specification or signature error

Cause​

CauseDescription
JWT format errorThe token does not conform to the three-part dot (.) separated format of header.payload.signature.
Signature algorithm errorKollus only supports the HS256 encryption algorithm. Specifying other algorithms such as RS256 will result in an error.
Missing required Payload fieldsThe mc[].mckey array field is missing, or the cuid value required by the channel's security policy has not been provided.
Base64Url encoding errorCharacters such as +, /, and = produced by standard Base64 encoding are included, breaking the communication specification.

Diagnosis​

Inspect the original structure of the issued JWT data.

  • Method A: Use the shell script below to parse the Payload structure.
echo "YOUR_JWT" | cut -d'.' -f2 | base64 -d 2>/dev/null | python3 -m json.tool
  • Method B: Use the validate_player_jwt tool to verify that the JWT conforms to the specification.

Solution​

Based on the diagnosis results, fix the token generation logic by locking the JWT encryption module's algorithm to HS256 and using the Base64URL encoding specification.

-4082​

  • Error code: -4082
  • Type: ERROR_MISMATCH_USER_KEY
  • Summary: The custom key passed via a specific field in the JWT Payload or the custom_key parameter does not match the key registered to the channel

Diagnosis and solution​

If different keys are used per development/production environment, check whether environment variables or configuration key values are being mixed up in the source code.

-4083​

  • Error code: -4083
  • Type: ERROR_ACCESS_WITHOUT_MEDIA_CONTENT_KEY
  • Summary: Missing media content key (the mc array in the JWT Payload is empty or the mckey field is absent)

Diagnosis and solution​

  • Incorrect example (array is empty)
{ "cuid": "user1", "mc": [] }
  • Correct example
{ "cuid": "user1", "mc": [{ "mckey": "MEDIA_CONTENT_KEY" }] }

-4085​

  • Error code: -4085
  • Type: ERROR_TOKEN_EXPIRED
  • Summary: Playback token expired (the expt value in the JWT Payload has expired)

Cause​

CauseDescription
expt value is in the pastThe expiration time parameter calculation logic is incorrect, resulting in a timestamp earlier than the current time being set.
Time unit confusionThe time unit of the timestamp (seconds or milliseconds) has been confused and entered incorrectly. (Refer to kollus://guidance/jwt-playback-expiry)
Server time synchronization differenceThe difference in system time between the JWT issuing server and the Kollus server exceeds the allowed range (±1 minute).
Reuse of an expired tokenThe client is reusing a previously expired JWT.

Diagnosis​

Query the expiry.expired field from the validate_player_jwt tool to check whether the token has been marked as expired based on the current time.