-4XXX (비디오 게이트웨이 에러)

재생 URL 요청 시 Kollus 비디오 게이트웨이가 반환하는 에러입니다. 개발 초기에 가장 자주 마주치는 에러들이므로 연동 코드를 점검하세요.

-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 서명에 사용한 보안 키(Security Key)가 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 Encoding 규격으로 토큰 생성 로직을 정정하세요.

-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 필드 값을 조회하여 현재 시각 기준으로 만료 처리되었는지 확인하세요.