업로드가 멈췄을 때 가장 먼저 확인할 것
쇼츠 업로드가 멈춰 있으면 두 가지가 동시에 궁금해진다. 왜 멈췄는지, 그리고 내일도 같은 일이 나는지다. 로그는 대개 한 줄뿐이라 판단하기 어렵다.
저는 업로드를 크론에 걸어 두고 자리를 비우는 편이다. 서버에 크론이 70개, 노트북에 9개 돌고 있어서 하나씩 들여다볼 수는 없다. 무인 작업의 실패는 조용하다. 로그 파일에 한 줄 남고 프로세스는 그냥 끝난다. 그래서 “왜 멈췄나”보다 “언제부터 멈췄나”를 먼저 찾는다.
실패 메시지 한 줄에는 답이 거의 들어 있다. HTTP 상태와 reason 문자열을 보면 쿼터 문제인지, 채널 업로드 상한인지, 레이트 리밋인지, 인증 문제인지 갈린다. 이걸 그냥 “업로드 실패”라고 뭉뚱그려 적어 두면 다음번에도 같은 자리에서 헤맨다.
- 마지막 성공 로그의 시각과 첫 실패 로그의 시각을 찾는다. 그 사이가 실패 구간이다.
- 실패 응답의 reason 문자열을 그대로 복사해 둔다. quotaExceeded, uploadLimitExceeded, rateLimitExceeded, 인증 관련 문자열 중 어디에 드는지 본다.
- 같은 시간대에 같은 프로젝트를 쓰던 다른 작업이 있었는지 본다. 쿼터는 프로젝트 단위로 같이 쓰이므로, 이걸 빼면 엉뚱한 업로드 코드만 뒤지게 된다.
할당량은 업로드 한 번에 얼마나 태우나
할당량은 프로젝트마다 하루치 단위가 정해져 있고, 작업 종류마다 소모하는 단위가 다르다. 업로드가 가장 비싸고, 검색 호출은 조회보다 훨씬 비싸다. 조회만 할 때는 여유가 있다가 검색을 섞은 날 금방 바닥나는 이유가 여기 있다.
정확한 단위 숫자는 이 글에 옮겨 적지 않았다. 정책과 단위는 바뀔 수 있고, 블로그에 숫자를 박아 두면 몇 달 뒤 틀린 정보가 된다. 콘솔의 할당량 페이지와 공식 문서에서 현재 값을 직접 확인하는 쪽이 맞다.
| 작업 | 소모 단위 | 메모 |
|---|---|---|
| videos.insert (업로드) | [공식 문서 값 기입] | 비중이 가장 크다 |
| search.list (검색) | [공식 문서 값 기입] | 조회보다 훨씬 비싸다 |
| videos.list, playlistItems.list (조회) | [공식 문서 값 기입] | 중복 확인용으로 쓰기 좋다 |
리셋은 태평양시 자정 기준이다. 11월에는 한국 시간으로 오후 5시에 바뀐다. 오전 9시에 쿼터가 바닥났다면, 그건 전날 오후 5시 이후에 쓴 단위가 쌓인 결과다. 이 시각도 정책이 바뀔 수 있으니 콘솔에서 한 번 더 확인하면 된다.
재시도해도 되는 경우와 안 되는 경우
| 원인 | 대표 신호 | 재시도 | 대기 방법 |
|---|---|---|---|
| 쿼터 소진 | quotaExceeded | 당일 재시도는 무의미 | 다음 리셋 시각 이후 큐 재개 |
| 채널 업로드 상한 | uploadLimitExceeded | 무의미 | 쿼터와 별개라 리셋으로 안 풀린다. 채널 상태를 보고 수동 판단 |
| 레이트 리밋 | rateLimitExceeded | 가능 | 간격을 점점 늘리고, 횟수 상한을 둔다 |
| 인증 오류 | invalidCredentials 계열 | 자동 재시도 금지 | 토큰과 권한 확인 후 재개, 알림 발송 |
재시도가 안전한 쪽은 일시적인 레이트 리밋 정도다. 위험한 건 응답만 유실된 경우다. 업로드 요청은 성공했는데 응답을 못 받으면, 그냥 다시 insert를 때릴 때 같은 영상이 두 번 올라간다. 재시도 횟수를 무제한으로 두면 실패 한 건이 예산을 연달아 먹으니, 계산만 해봐도 그 손실이 분명해서 처음부터 상한을 걸었다.
중복을 막는 방법은 업로드할 때 설명란 끝에 작업 ID를 심어 두고, 재시도 전에 업로드 목록에서 그 ID를 먼저 찾는 것이다. 검색 호출 대신 업로드 재생목록을 읽으면 비용이 훨씬 적다.
def find_existing_upload(youtube, uploads_playlist_id, job_id, max_pages=2):
token = None
for _ in range(max_pages):
resp = youtube.playlistItems().list(
part="snippet",
playlistId=uploads_playlist_id,
maxResults=50,
pageToken=token,
).execute()
for item in resp.get("items", []):
if f"job:{job_id}" in item["snippet"].get("description", ""):
return item["snippet"]["resourceId"]["videoId"]
token = resp.get("nextPageToken")
if not token:
break
return None
응답이 유실되면 이 함수를 먼저 돌리고, 영상이 나오면 성공으로 기록한다. None이면 그때 재시도한다. 한계가 있다. 업로드 직후에는 목록 반영이 늦어서 몇 초 기다린 뒤 조회해야 하고, 사람이 설명란을 고치면 작업 ID가 지워져서 중복 확인이 깨진다. 채널 상한은 이 방식으로도 해결되지 않는다.

하루 편수를 쿼터 안에서 계산하는 방법
편수는 거꾸로 계산한다. 일 한도에서 시작해서, 고정으로 빠져나갈 조회 예약분과 재시도 예산을 먼저 뺀 나머지를 업로드 한 번의 단위로 나눈다.
편수 = 내림((일 한도 - 조회·검색 예약분 - 재시도 예산) ÷ 업로드 1회 단위)
| 항목 | 넣을 값 |
|---|---|
| 일 한도 | 콘솔 할당량 페이지의 값 [기입] |
| 조회·검색 예약분 | 하루 작업 수 곱하기 작업당 단위 [실측 기입] |
| 재시도 예산 | 실패를 몇 번까지 감당할지 정한 단위 [실측 기입] |
| 업로드 1회 단위 | 공식 문서 값 [기입] |
| 편수 | 위 식을 내림한 값 |
나눗셈 뒤에 남는 자투리 단위는 버리지 말고 재시도 예산으로 돌린다. 재시도 예산이 0이면 실패 한 번에 그날 발행이 통째로 밀린다.
이 계산은 쿼터만 본다. 채널 업로드 상한은 따로 확인해야 한다. 저는 계산 시트와 콘솔의 사용량 그래프를 대조하는 습관을 들이는 중인데, 예측과 실측이 얼마나 맞는지는 아직 데이터가 충분히 쌓이지 않았다.
증설 신청보다 먼저 할 것
쿼터가 부족하면 증설을 떠올리기 쉽다. 저도 그랬다. 그런데 순서는 측정, 호출 정리, 발행 시간 분산, 그다음에 증설이어야 한다고 정했다. 증설 심사 기간이 길 수 있어서, 기다리는 동안 운영이 멈추면 의미가 없다.
프로젝트를 여러 개로 나눠서 쿼터를 늘리는 방법은 쓰지 않는다. 약관과 정책에 걸릴 수 있어서, 공식 정책을 먼저 읽어야 한다. 발행 큐를 시간대별로 나누면 업로드가 조금 늦어지는 대신 한꺼번에 몰려 실패하는 일이 줄어든다. 이 교환은 감수할 만하다고 봤다.

조용한 실패를 잡는 로그와 알림
무인 크론은 실패해도 소리가 없다. 로그에 무엇을 남겨야 나중에 판단할 수 있는지부터 정했다.
| 필드 | 용도 |
|---|---|
| 시각 | 리셋 구간에 맞춰 사용량 집계 |
| 작업 ID | 중복 확인 키 |
| 엔드포인트 | 업로드와 조회 구분 |
| 누적 사용 단위 | 예산과 대조 |
| HTTP 상태, reason | 원인 분류 |
| 재시도 횟수 | 재시도 예산 소진 확인 |
{
"ts": "2026-11-14T06:12:09+09:00",
"job_id": "shorts-sample",
"endpoint": "videos.insert",
"units_used_cumulative": "[실제 로그 수치 기입]",
"http_status": "[실제 값]",
"reason": "quotaExceeded",
"retry_count": 0,
"action": "queue_hold_until_reset"
}
알림은 세 가지 조건에만 건다. 연속으로 두 번 실패할 때, 잔여 쿼터가 임계치 아래로 떨어질 때, 큐에 쌓인 작업이 정해 둔 시간을 넘겨 기다릴 때다. 임계치 값은 각자 운영 방식에 맞게 정하면 된다. 알림이 없던 시기에는 실패를 다음 날에야 알아챘고, 그 뒤로는 이 세 조건을 먼저 붙이는 쪽으로 바꿨다.

이 방식이 맞지 않는 경우와 오늘 할 일
하루에 몇 편 안 올린다면 이 설계는 과하다. 그 정도면 수동 업로드가 더 빠를 수 있다. 쿼터 계산, 분류, 알림 세 가지를 맞춰 두는 데 드는 시간이 편수보다 클 수도 있다.
이 방식이 다 막아 주지는 못한다. 정책이 바뀌면 계산식의 단위 값을 다시 넣어야 하고, 설명란 작업 ID는 사람 손에 지워질 수 있다. 채널 업로드 상한을 자동으로 피하는 방법은 아직 못 찾았다.
- 측정: 콘솔에서 오늘 사용량과 리셋 시각을 확인하고, 실패 로그의 reason을 복사해 둔다.
- 분류: 실패를 쿼터, 채널 상한, 레이트 리밋, 인증 가운데 하나로 나눠 재시도 여부를 정한다.
- 알림: 연속 두 번 실패, 잔여 쿼터 임계치, 큐 적체 시간 세 조건을 먼저 건다.
자주 묻는 질문
quotaExceeded가 뜨면 바로 재시도해도 되나요?
당일 재시도는 의미가 없다. 리셋 시각 이후에 큐를 다시 열어야 한다.
uploadLimitExceeded는 기다리면 풀리나요?
쿼터와 별개의 채널 상한이라 리셋 대기로 해결되지 않는다. 채널 상태를 확인하고 수동으로 판단해야 한다.
업로드가 성공했는데 응답만 못 받았다면 어떻게 하나요?
재생목록에서 작업 ID가 담긴 설명란을 찾는다. 있으면 성공으로 기록하고, 없으면 재시도한다.
하루에 쇼츠를 몇 개까지 올릴 수 있나요?
일 한도에서 조회 예약분과 재시도 예산을 뺀 값을 업로드 1회 단위로 나눈 몫이다. 단위 값은 공식 문서와 콘솔에서 확인한다.
할당량을 늘리기 전에 무엇을 해야 하나요?
사용량을 측정하고, 불필요한 호출을 줄이고, 발행 시간을 분산한 뒤에도 부족할 때 증설을 신청한다.
참고한 공식 문서
혼자 자동화로 서비스를 굴리는 아일리고입니다. 숏폼 영상은 제가 만든 ClipSquare 로 뽑습니다.
