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

아래 표에서는 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 매개변수 값이 올바른지 확인하세요.