YouTube Data API - 오류

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

이 문서에서는 YouTube Data API 작업에서 반환할 수 있는 다양한 유형의 오류를 확인합니다. 개별 메소드의 오류 목록은 해당 메소드의 참조 문서에서도 확인할 수 있습니다.

  1. 일반 오류
  2. activities
  3. channelBanners
  4. channels
  5. guideCategories
  6. playlistItems
  7. playlists
  8. search
  9. subscriptions
  10. thumbnails
  11. videoCategories
  12. videos

일반 오류

아래 표에서는 특정 API 메소드에 제한되지 않는 API 오류 메시지를 확인합니다.

Core API errors

오류 유형 오류 세부정보 설명
forbidden forbidden 액세스 금지됨. 요청이 제대로 인증되지 않았을 수 있습니다.
quotaExceeded quotaExceeded 할당량을 초과했기 때문에 요청을 완료할 수 없습니다.

Common request errors

오류 유형 오류 세부정보 설명
badRequest incompatibleParameters 요청이 같은 요청에 사용할 수 없는 둘 이상의 매개변수를 지정합니다.
badRequest invalidFilters 요청이 잘못된 필터 매개변수를 지정합니다.
badRequest invalidPageToken 요청이 잘못된 페이지 토큰을 지정합니다.
badRequest missingRequiredParameter 요청에 필수 매개변수가 없습니다.
badRequest unexpectedParameter 요청이 예기치 않은 매개변수를 지정합니다.
forbidden accountDelegationForbidden 인증된 사용자가 지정된 Google 계정을 대신하여 작업할 수 없습니다.
forbidden authenticatedUserAccountClosed 인증된 사용자의 YouTube 계정이 삭제되었습니다. 인증된 사용자가 다른 Google 계정을 대신하여 작업 중인 경우 이 오류는 해당 Google 계정에 적용됩니다.
forbidden authenticatedUserAccountSuspended 인증된 사용자의 YouTube 계정이 일시 중지되었습니다. 인증된 사용자가 다른 Google 계정을 대신하여 작업 중인 경우 이 오류는 해당 Google 계정에 적용됩니다.
forbidden authenticatedUserNotChannel 이 요청에서 인증된 사용자를 통해 채널을 확인해야 하지만, 그렇게 하지 못했습니다. 요청이 인증되었고 onBehalfOfContentOwner 위임 매개변수를 사용하는 경우 onBehalfOfContentOwnerChannel 매개변수도 설정해야 합니다.
forbidden channelClosed 요청에서 확인된 채널이 삭제되었습니다.
forbidden channelNotFound 요청에서 확인된 채널을 찾을 수 없습니다.
forbidden channelSuspended 요청에서 확인된 채널이 일시 중지되었습니다.
forbidden cmsUserAccountNotFound CMS 사용자는 지정된 콘텐츠 소유자를 대신하여 작업할 수 없습니다.
forbidden insufficientCapabilities CMS 사용자의 권한이 충분하지 않습니다.
notFound contentOwnerAccountNotFound 지정된 콘텐츠 소유자 계정을 찾을 수 없습니다.

Request context errors

오류 유형 오류 세부정보 설명
badRequest invalidLanguage hl 매개변수 값이 잘못된 언어 코드를 지정합니다.
badRequest invalidMine 요청에 mine 매개변수를 사용할 수 없습니다.
badRequest invalidPart 요청의 part 매개변수가 동시에 작성할 수 없는 부분을 지정합니다.
badRequest invalidRegionCode regionCode 매개변수가 잘못된 지역 코드를 지정합니다.
badRequest unexpectedPart 요청의 part 매개변수가 예기치 않은 값을 지정합니다
badRequest unknownPart 요청의 part 매개변수가 알 수 없는 값을 지정합니다.
badRequest unsupportedLanguageCode hl 매개변수 값이 지원되지 않는 언어 코드를 지정합니다.
badRequest unsupportedRegionCode regionCode 매개변수가 지원되지 않는 지역 코드를 지정합니다.
unauthorized authorizationRequired 요청이 mine 매개변수를 사용하지만 제대로 인증되지 않았습니다.
unauthorized youtubeSignupRequired 이 오류는 사용자에게 연결되지 않은 Google 계정이 있음을 나타냅니다. 즉 Google 계정이 있지만 YouTube 채널은 없습니다. 이러한 사용자는 사용자 인증에 따라 동영상을 평가하거나 동영상을 watch_later 재생목록에 추가하는 등 다양한 기능을 사용할 수 있습니다. 하지만 동영상을 업로드하려면 YouTube 채널이 필요합니다. Gmail 계정이나 Android 기기가 있는 사용자는 Google 계정이 있겠지만, 해당 Google 계정이 YouTube 채널과 연결되어 있지 않을 수도 있습니다.

OAuth 2.0 서비스 계정 흐름을 사용할 때 일반적으로 나타나는 오류입니다. YouTube는 서비스 계정을 지원하지 않으며, 서비스 계정으로 인증을 시도할 경우 이 오류가 발생합니다.

Google 계정 지원에 대해 소개하는 YouTube API 블로그 게시물에서도 youtubeSignupRequired 오류를 자세히 논의하고 있습니다. 게시물에서 설명하는 오류는 API 버전 2.1이지만 오류의 의미는 같습니다.

activities

아래 표에서는 activities 리소스와 관련된 호출에 대한 응답으로 API가 반환하는 오류 메시지를 확인합니다. 이러한 메소드는 일반적인 오류 섹션에 있는 오류도 반환할 수 있습니다.

activities.list

오류 유형 오류 세부정보 설명
notFound channelNotFound 요청의 channelId 매개변수로 식별된 채널 ID를 찾을 수 없습니다.
notFound homeChannelNotFound 현재 인증된 사용자에 대한 YouTube 홈 페이지 피드를 찾을 수 없습니다.
unauthorized authorizationRequired 요청이 home 매개변수를 사용하지만 제대로 인증되지 않았습니다.

activities.insert

오류 유형 오류 세부정보 설명
badRequest bulletinTextRequired 게시판 글에 텍스트를 제공하려면 요청이 snippet 개체의 description 속성을 사용해야 합니다.
notFound playlistNotFound 게시판 글과 연결하려는 동영상을 YouTube에서 찾을 수 없습니다. contentDetails.bulletinPosted.playlistId 속성의 값을 확인하세요.
notFound videoNotFound 게시판 글과 연결하려는 동영상을 YouTube에서 찾을 수 없습니다. contentDetails.bulletinPosted.videoId 속성의 값을 확인하세요.
userRateLimitExceeded rateLimitExceeded 할당량을 초과했기 때문에 요청을 완료할 수 없습니다.

channelBanners

아래 표에서는 channelBanners 리소스와 관련된 호출에 대한 응답으로 API가 반환하는 오류 메시지를 확인합니다. 이러한 메소드는 일반적인 오류 섹션에 있는 오류도 반환할 수 있습니다.

channelBanners.insert

오류 유형 오류 세부정보 설명
badRequest mediaBodyRequired 요청에 이미지 콘텐츠가 포함되어 있지 않습니다.

channels

아래 표에서는 channels 리소스와 관련된 호출에 대한 응답으로 API가 반환하는 오류 메시지를 확인합니다. 이러한 메소드는 일반적인 오류 섹션에 있는 오류도 반환할 수 있습니다.

channels.list

오류 유형 오류 세부정보 설명
forbidden channelForbidden id 매개변수로 지정된 채널이 요청을 지원하지 않거나 요청이 제대로 인증되지 않았습니다.
notFound categoryNotFound categoryId 매개변수로 식별된 카테고리를 찾을 수 없습니다. 유효한 값 목록을 검색하려면 guideCategories.list 메소드를 사용하세요.
notFound channelNotFound id 매개변수에 지정된 채널을 찾을 수 없습니다.

channels.update

오류 유형 오류 세부정보 설명
badRequest brandingValidationError brandingSettings 개체의 값 중 하나를 확인하지 못했습니다. channels.list 메소드를 사용해 채널의 기존 설정을 검색하고 channels 리소스 문서의 안내에 따라 속성 값을 업데이트하세요.
badRequest invalidBrandingOption 지정된 브랜드 설정 중 하나가 존재하지 않습니다. channels.list 메소드를 사용해 유효한 값을 검색하고 channels 리소스 문서의 안내에 따라 이 값을 업데이트하세요.
badRequest invalidCornerPosition 요청 메타데이터가 프로모션 항목이 표시될 위치를 확인하기 위해 지정한 코너 위치가 잘못되었습니다. 요청이 보낸 리소스에서 invideoPromotion.position.cornerPosition 속성 값을 확인하세요.
badRequest invalidItemType 요청 메타데이터가 invideoPromotion 부분에 잘못된 항목 유형을 지정합니다 요청이 보낸 리소스에서 invideoPromotion.items[].type 속성 값을 확인하세요.
badRequest invalidPositionOffset 요청 메타데이터가 프로모션 항목을 동영상 플레이어에 배치하는 방법을 결정하기 위해 지정한 위치 유형이 잘못되었습니다. 요청이 보낸 리소스에서 invideoPromotion.position.type 속성 값을 확인하세요.
badRequest invalidTimingOffset 요청 메타데이터가 프로모션 항목을 동영상 플레이어에 표시할 시기를 결정하기 위해 지정한 타이밍 오프셋이 잘못되었습니다. 요청이 보낸 리소스에서 invideoPromotion.timing.offsetMs 속성 값을 확인하세요.
badRequest invalidTimingType 요청 메타데이터가 프로모션 항목을 동영상 플레이어에 표시할 시기를 결정하기 위해 지정한 타이밍 메소드가 잘못되었습니다. 요청이 보낸 리소스에서 invideoPromotion.timing.type 속성 값을 확인하세요.
forbidden channelForbidden id 매개변수에 지정된 채널이 요청을 지원하지 않거나 요청이 제대로 인증되지 않았습니다.
notFound channelNotFound id .매개변수로 식별된 채널을 찾을 수 없거나 브랜드 옵션이 없습니다.
notFound unknownChannelId API 요청이 업데이트하려는 채널을 찾을 수 없습니다. 채널 ID가 정확한지 확인하기 위해 요청이 보낸 channel 리소스에서 id 속성 값을 확인하세요.
notFound unknownVideoId 프로모션 항목으로 지정한 동영상 ID를 찾을 수 없습니다.
required requiredCornerPosition 요청 메타데이터는 YouTube가 플레이어에서 프로모션 항목을 표시할 위치를 결정할 수 있도록 코너 위치를 지정해야 합니다. 요청이 보내는 리소스에서 invideoPromotion.position.cornerPosition 속성 값을 설정하세요.
required requiredItemType 요청 메타데이터가 프로모션 항목의 유형을 지정해야 합니다. 요청이 보내는 리소스에서 invideoPromotion.items[].type 속성 값을 설정하세요.
required requiredPositionOffset YouTube가 프로모션 항목을 표시할 방법을 결정할 수 있도록 요청 메타데이터가 위치 유형을 지정해야 합니다. 요청이 보내는 리소스에서 invideoPromotion.position.type 속성 값을 설정하세요.
required requiredTimingOffset YouTube가 프로모션 항목을 표시할 시간을 결정할 수 있도록 요청 메타데이터가 타이밍 오프셋을 지정해야 합니다. 요청이 보내는 리소스에서 invideoPromotion.timing.offsetMs 속성 값을 설정하세요.
required requiredTimingType YouTube가 프로모션 항목을 표시할 시간을 결정할 수 있도록 요청 메타데이터가 타이밍 메소드를 지정해야 합니다. 요청이 보내는 리소스에서 invideoPromotion.timing.type 속성 값을 설정하세요.
required requiredVideoId 프로모션 항목을 구분하기 위해 요청 메타데이터가 동영상 ID를 지정해야 합니다.

guideCategories

아래 표에서는 guideCategories 리소스와 관련된 호출에 대한 응답으로 API가 반환하는 오류 메시지를 확인합니다. 이러한 메소드는 일반적인 오류 섹션에 있는 오류도 반환할 수 있습니다.

guideCategories.list

오류 유형 오류 세부정보 설명
notFound notFound id 매개변수로 식별된 가이드 카테고리를 찾을 수 없습니다. 유효한 값 목록을 검색하려면 guideCategories.list 메소드를 사용하세요.

playlistItems

아래 표에서는 playlistItems 리소스와 관련된 호출에 대한 응답으로 API가 반환하는 오류 메시지를 확인합니다. 이러한 메소드는 일반적인 오류 섹션에 있는 오류도 반환할 수 있습니다.

playlistItems.delete

오류 유형 오류 세부정보 설명
forbidden playlistItemsNotAccessible 지정된 재생목록 항목을 삭제할 수 있도록 요청이 제대로 인증되지 않았습니다.
notFound playlistItemNotFound 요청의 id 매개변수로 식별된 재생목록 항목을 찾을 수 없습니다.

playlistItems.insert

오류 유형 오류 세부정보 설명
duplicate videoAlreadyInPlaylist 재생목록에 추가하려는 동영상이 이미 재생목록에 있습니다.
forbidden playlistContainsMaximumNumberOfVideos 재생목록의 항목 수가 최대 허용치에 도달했습니다.
invalidValue invalidPlaylistItemPosition 요청이 재생목록 항목의 위치를 잘못되거나 지원되지 않는 값으로 설정하려 합니다. 리소스의 snippet 안에 있는 position 속성 값을 확인하세요.
invalidValue invalidResourceType 리소스 ID에 지정된 type이 이 작업에서 지원되지 않습니다. 리소스 ID를 통해 항목이 재생목록에 추가되고 있음을 확인합니다. 예: youtube#video
notFound playlistNotFound 요청의 playlistId 매개변수로 식별된 재생목록을 찾을 수 없습니다.
notFound videoNotFound 재생목록에 추가하려는 동영상을 찾을 수 없습니다. videoId 속성 값이 올바른지 확인하세요.
required channelIdRequired 요청이 필수 channelId 속성 값을 지정하지 않았습니다.
required playlistIdRequired 요청이 필수 playlistId 속성 값을 지정하지 않았습니다.
required resourceIdRequired 요청에 snippet 개체가 resourceId를 지정하는 리소스가 포함되어야 합니다.

playlistItems.list

오류 유형 오류 세부정보 설명
forbidden playlistItemsNotAccessible 지정된 재생목록을 검색할 수 있도록 요청이 제대로 인증되지 않았습니다.
notFound playlistNotFound 요청의 playlistId 매개변수로 식별된 재생목록을 찾을 수 없습니다.
notFound videoNotFound 요청의 videoId 매개변수로 식별된 동영상을 찾을 수 없습니다.
required playlistIdRequired 구독 요청이 필수 playlistId 속성 값을 지정하지 않았습니다.

playlistItems.update

오류 유형 오류 세부정보 설명
invalidValue invalidPlaylistItemPosition 요청이 재생목록 항목의 위치를 잘못되거나 지원되지 않는 값으로 설정하려고 합니다. 리소스의 position 안에 있는 snippet 속성 값을 확인하세요.
invalidValue invalidResourceType 리소스 ID에 지정된 type이 이 작업에서 지원되지 않습니다. 리소스 ID를 통해 항목이 재생목록에 추가되고 있음을 확인합니다. 예: youtube#video
invalidValue invalidSnippet 요청이 잘못된 snippet 속성 값을 지정합니다.
notFound playlistItemNotFound 요청의 id 속성으로 식별된 재생목록 항목을 찾을 수 없습니다.
notFound playlistNotFound 요청의 playlistId 매개변수로 식별된 재생목록을 찾을 수 없습니다.
required channelIdRequired 요청이 필수 channelId 속성 값을 지정하지 않았습니다.
required playlistIdRequired 요청이 필수 playlistId 속성 값을 지정하지 않았습니다.
required playlistItemIdRequired 요청에 지정된 재생목록 항목 리소스가 업로드 중인 재생목록 항목을 확인하려면 id 속성을 사용해야 합니다.

playlists

아래 표에서는 playlists 리소스와 관련된 호출에 대한 응답으로 API가 반환하는 오류 메시지를 확인합니다. 이러한 메소드는 일반적인 오류 섹션에 있는 오류도 반환할 수 있습니다.

playlists.delete

오류 유형 오류 세부정보 설명
notFound playlistNotFound 요청의 id 매개변수로 식별된 재생목록을 찾을 수 없습니다.

playlists.insert

오류 유형 오류 세부정보 설명
invalidValue invalidPlaylistSnippet 요청에서 잘못된 재생목록 스니펫을 제공합니다.
required playlistTitleRequired 요청에 재생목록의 제목을 지정해야 합니다.

playlists.update

오류 유형 오류 세부정보 설명
invalidValue invalidPlaylistSnippet 요청이 잘못된 재생목록 스니펫을 제공합니다.
notFound playlistNotFound 요청의 id 매개변수로 식별된 재생목록을 찾을 수 없습니다.
required playlistTitleRequired 요청에서 재생목록의 제목을 지정해야 합니다.

아래 표에서는 search 리소스와 관련된 호출에 대한 응답으로 API가 반환하는 오류 메시지를 확인합니다. 이러한 메소드는 일반적인 오류 섹션에 있는 오류도 반환할 수 있습니다.

search.list

오류 유형 오류 세부정보 설명
badRequest invalidSearchFilter 요청에 잘못된 조합의 검색 필터 및/또는 제한이 있습니다.
badRequest invalidVideoId relatedToVideo 매개변수에 지정된 동영상 ID가 잘못되었습니다.

subscriptions

아래 표에서는 subscriptions 리소스와 관련된 호출에 대한 응답으로 API가 반환하는 오류 메시지를 확인합니다. 이러한 메소드는 일반적인 오류 섹션에 있는 오류도 반환할 수 있습니다.

subscriptions.delete

오류 유형 오류 세부정보 설명
badRequest accountClosed 구독정보를 만들려는 계정이 삭제되었습니니다.
badRequest accountSuspended 구독정보를 만들려는 계정이 일시 중지되었습니다.
forbidden subscriptionForbidden 요청이 제대로 인증되지 않았거나 이 채널에서 지원하지 않습니다.
notFound subscriptionNotFound 삭제하려는 구독정보를 찾을 수 없습니다. 요청 id 매개변수 값이 올바른지 확인하세요.

subscriptions.insert

오류 유형 오류 세부정보 설명
badRequest accountClosed 구독정보를 만들려는 계정이 삭제되었습니니다.
badRequest accountSuspended 구독정보를 만들려는 계정이 일시 중지되었습니다.
badRequest subscriptionDuplicate 만들려는 구독정보가 이미 존재합니다.
forbidden subscriptionForbidden 요청이 제대로 인증되지 않았거나 이 채널에서 지원하지 않습니다.
notFound publisherNotFound 요청의 snippet.resourceId 속성으로 지정된 리소스를 찾을 수 없습니다.
notFound subscriberNotFound 요청에서 확인된 구독자를 찾을 수 없습니다.
required publisherRequired 구독 중인 채널을 확인하려면 요청에서 확인된 구독정보 리소스에 snippet.resourceId 속성을 사용해야 합니다.

subscriptions.list

오류 유형 오류 세부정보 설명
forbidden accountClosed 구독자의 계정이 삭제되어 구독정보를 검색할 수 없습니다.
forbidden accountSuspended 구독자의 계정이 일시 중지되어 구독정보를 검색할 수 없습니다.
forbidden subscriptionForbidden 요청한 구독정보에 요청자가 액세스할 수 없습니다.
notFound subscriberNotFound 요청에서 확인된 구독자를 찾을 수 없습니다.

thumbnails

아래 표에서는 thumbnails 리소스와 관련된 호출에 대한 응답으로 API가 반환하는 오류 메시지를 확인합니다. 이러한 메소드는 일반적인 오류 섹션에 있는 오류도 반환할 수 있습니다.

thumbnails.set

오류 유형 오류 세부정보 설명
badRequest mediaBodyRequired 요청에 이미지 콘텐츠가 포함되어 있지 않습니다.
forbidden forbidden 인증된 사용자에게 맞춤 동영상 미리보기 이미지를 업로드하고 설정할 수 있는 권한이 없습니다.
forbidden forbidden 지정 동영상에 미리보기 이미지를 설정할 수 없습니다. 요청이 제대로 인증되지 않았을 수 있습니다.
notFound videoNotFound 미리보기 이미지를 삽입하려는 동영상을 찾을 수 없습니다. 요청 videoId 매개변수 값이 올바른지 확인하세요.

videoCategories

아래 표에서는 videoCategories 리소스와 관련된 호출에 대한 응답으로 API가 반환하는 오류 메시지를 확인합니다. 이러한 메소드는 일반적인 오류 섹션에 있는 오류도 반환할 수 있습니다.

videoCategories.list

오류 유형 오류 세부정보 설명
notFound videoCategoryNotFound id 매개변수로 식별된 동영상 카테고리를 찾을 수 없습니다. 유효한 값 목록을 검색하려면 videoCategories.list 메소드를 사용하세요.

videos

아래 표에서는 videos 리소스와 관련된 호출에 대한 응답으로 API가 반환하는 오류 메시지를 확인합니다. 이러한 메소드는 일반적인 오류 섹션에 있는 오류도 반환할 수 있습니다.

videos.insert

오류 유형 오류 세부정보 설명
badRequest invalidCategoryId snippet.categoryId 속성이 잘못된 카테고리 ID를 지정합니다. 지원되는 카테고리를 검색하려면 videoCategories.list 메소드를 사용하세요.
badRequest invalidDescription 요청 메타데이터가 잘못된 동영상 설명을 지정합니다.
badRequest invalidFilename Slug 헤더에 지정된 동영상 파일 이름이 잘못되었습니다
badRequest invalidRecordingDetails 요청 메타데이터의 recordingDetails 개체가 잘못된 녹화 세부정보를 지정합니다.
badRequest invalidTags 요청 메타데이터가 잘못된 동영상 키워드를 지정합니다.
badRequest invalidTitle 요청 메타데이터가 잘못된 동영상 제목을 지정합니다.
badRequest invalidVideoGameRating 요청 메타데이터가 잘못된 비디오 게임 등급을 지정합니다.
badRequest invalidVideoMetadata 요청 메타데이터가 잘못되었습니다.
badRequest mediaBodyRequired 요청에 동영상 콘텐츠가 없습니다.
forbidden forbiddenLicenseSetting 요청이 동영상에 잘못된 라이선스를 설정하려고 합니다.
forbidden forbiddenPrivacySetting 요청이 동영상에 대해 잘못된 개인정보 보호 설정을 지정하려고 합니다.

videos.list

오류 유형 오류 세부정보 설명
badRequest videoChartNotFound 요청한 동영상 차트가 지원되지 않거나 동영상 차트를 사용할 수 없습니다.
forbidden forbidden 요청이 평점 정보에 액세스할 수 없습니다. 요청이 myRating 매개변수를 사용하도록 제대로 인증되지 않은 경우 이 오류가 발생할 수 있습니다.

videos.delete

오류 유형 오류 세부정보 설명
forbidden forbidden 삭제하려는 동영상을 삭제할 수 없습니다. 요청이 제대로 인증되지 않았을 수 있습니다.
notFound videoNotFound 삭제하려는 동영상을 찾을 수 없습니다. 요청 id 매개변수 값이 올바른지 확인하세요.

videos.update

오류 유형 오류 세부정보 설명
badRequest invalidRequest 요청 메타데이터가 잘못되었습니다.
forbidden forbidden
forbidden forbiddenLicenseSetting 요청이 동영상에 잘못된 라이선스를 설정하려고 합니다.
forbidden forbiddenPrivacySetting 요청이 동영상에 대해 잘못된 개인정보 보호 설정을 지정하려고 합니다.
notFound videoNotFound 업데이트하려는 동영상을 찾을 수 없습니다. 요청 본문에 있는 id 필드 값이 올바른지 확인하세요.

videos.rate

오류 유형 오류 세부정보 설명
forbidden forbidden 평가하려는 동영상을 평가할 수 없습니다. 요청이 제대로 인증되지 않았을 수 있습니다.
notFound videoNotFound 평가하려는 동영상을 찾을 수 없습니다. 요청 id 매개변수 값이 올바른지 확인하세요.