YouTube API Quota Exceeded: Causes and Fixes

모든 Google Cloud 프로젝트는 기본적으로 YouTube Data API v3에 하루 10,000단위의 할당량을 받으며, 태평양 표준시 자정에 초기화됩니다 - 이월도 없고 조기 초기화를 유도할 방법도 없습니다. 할당량은 API 키가 아니라 프로젝트 단위로 추적되므로, 같은 프로젝트에서 두 번째 키를 생성해도 별도의 할당량 풀이 생기지 않습니다.

모든 API 호출은 요청 수가 아니라 단위를 소모하며, 비용은 균등하지 않습니다. 개발자가 실제로 많이 사용하는 엔드포인트 전체 비용은 다음과 같습니다:

검색 1회당 100단위이므로, 자막 하나 다운로드하기 전에 검색 호출 100번만으로도 프로젝트의 하루 할당량을 전부 소진할 수 있습니다. 이는 소규모 프로젝트가 한도에 걸리는 가장 흔한 방식입니다: 요청을 10,000번 한 게 아니라, 비용이 큰 요청을 몇백 번 한 것입니다. 반면 videos.list, channels.list, playlistItems.list는 각각 1단위로 저렴합니다 - 동영상, 채널, 재생목록 ID를 이미 알고 있다면 이런 호출은 하루 예산을 거의 소모하지 않습니다.

1. API 키가 속한 프로젝트의 Google Cloud Console을 여세요.
2. APIs & Services → YouTube Data API v3 → Quotas & System Limits로 이동하세요.
3. 여기서 일일 쿼리 수와 분당 한도 대비 현재 사용량을 확인할 수 있으며, 실시간이 아니라 약간의 지연을 두고 업데이트됩니다.

10,000번 요청도 하기 전에 이미 한도에 근접했다면, 이 화면으로 버그가 아니라 위에서 설명한 고비용 호출 문제임을 확인할 수 있습니다.

둘 다 403을 반환하고 일상 대화에서는 "할당량 오류"로 뭉뚱그려지지만, 실제로는 원인과 해결책이 다른 별개의 문제입니다:

• quotaExceeded (원인: dailyLimitExceeded) - 프로젝트가 하루 단위 할당량을 모두 소진했습니다. 태평양 표준시 자정 초기화를 기다리거나, 호출당 비용을 줄이거나, 할당량 증가 승인을 받는 것 외에는 해결할 방법이 없습니다.
• rateLimitExceeded - 하루 총량과 무관하게 짧은 시간 창 안에 요청을 너무 빠르게 보내고 있습니다. 이는 예산 문제가 아니라 속도 조절 문제입니다 - 백오프로 올바르게 처리하는 방법은 속도 제한 가이드를 참고하세요.

1. 적극적으로 캐시하세요. 할당량은 사용자 대면 요청이 아니라 API 호출당 부과됩니다 - 같은 동영상의 자막을 반복해서 다시 가져온다면, 매번 다시 API를 호출하는 대신 결과를 캐시하세요(단순한 인메모리 TTL 캐시라도).
2. 직접 ID 조회로 가능한 곳에서는 search.list를 피하세요. 동영상, 채널, 재생목록 ID를 이미 갖고 있다면 해당하는 .list 호출이 검색보다 100배 저렴합니다.
3. ID 조회를 일괄 처리하세요. videos.list는 호출당 쉼표로 구분된 ID를 최대 50개까지 받으며 비용은 단일 ID 조회와 동일한 1단위입니다 - 50개 동영상을 한 번에 하나씩 가져오는 것은 이유 없이 50배 더 비쌉니다.
4. 실제 프로덕션 사용량으로 근거를 마련한 뒤 할당량 증가를 요청하세요. Cloud Console 할당량 페이지에 연결된 YouTube API Services Audit and Quota Extension 양식을 통해 신청합니다. 즉시 승인이 아니라 수동 검토를 예상하세요.
5. 자체 YouTube 할당량을 소모하지 않는 스크립트 API를 사용하세요. GetYouTubeTranscript의 API는 사용자의 키로 captions.download를 프록시하는 대신 자체 인프라에서 스크립트를 가져오므로, 관리해야 할 하루 10,000단위 상한이 없습니다 - 요금제 자체의 요청 속도 제한만 신경 쓰면 됩니다.

cURL:

curl "https://getyoutubetranscript.com/api/v1/transcript?v=dQw4w9WgXcQ" \
  -H "Authorization: Bearer sk_live_..."

Node.js:

const res = await fetch(
  "https://getyoutubetranscript.com/api/v1/transcript?v=dQw4w9WgXcQ",
  { headers: { Authorization: `Bearer ${process.env.GETYOUTUBETRANSCRIPT_API_KEY}` } }
);
const { data } = await res.json();
console.log(data.transcript);

Python:

import os, requests

res = requests.get(
    "https://getyoutubetranscript.com/api/v1/transcript",
    params={"v": "dQw4w9WgXcQ"},
    headers={"Authorization": f"Bearer {os.environ['GETYOUTUBETRANSCRIPT_API_KEY']}"},
)
print(res.json()["data"]["transcript"])

이 요청은 Google Cloud 프로젝트의 YouTube Data API 할당량 단위가 아니라 GetYouTubeTranscript 요금제의 1크레딧을 소모합니다. 대시보드에서 카드 등록 없이 무료 크레딧 100개를 받거나, 전체 API 문서를 확인하세요.