본문으로 건너뛰기

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