YouTube API: Limit Exceeded — как определить причину ошибки

Сообщение limit exceeded при работе с YouTube API не указывает на одну конкретную проблему. Под похожим описанием могут скрываться исчерпанная квота проекта Google Cloud, ограничение загрузок отдельного канала, ошибка OAuth, запрет прав или некорректный запрос. Исправления у них разные: увеличение квоты проекта не снимет лимит канала, а повторная авторизация не исправит неверный параметр API.

Начните не с догадки, а с полного ответа API: HTTP-статуса, error.errors[].reason, сообщения, метода, времени и идентификатора проекта. Именно поле reason обычно позволяет выбрать правильную ветку диагностики.

Четыре категории, которые нельзя смешивать

1. Квота проекта YouTube Data API

YouTube Data API учитывает стоимость запросов в единицах квоты проекта Google Cloud. Разные методы расходуют разное количество единиц, а ошибочные запросы тоже могут иметь стоимость. Когда суточная квота проекта исчерпана, ответы обычно указывают на квоту, например через причину quotaExceeded или связанную с ней формулировку.

Это ограничение относится к проекту API, а не к одному каналу. Если несколько пользователей публикуют через одно приложение и ошибки начинаются у всех примерно одновременно, проектная квота становится вероятной причиной.

Проверяйте:

• тот ли Google Cloud project использует рабочее приложение;
• включён ли YouTube Data API v3;
• текущее потребление квоты в Google Cloud Console;
• какие методы создают основной расход;
• не выполняет ли приложение лишние повторы, опросы или дублирующие запросы;
• совпадает ли дата сброса и часовой пояс с тем, что показывает консоль.

Не вставляйте в документацию старые числа из блогов. Текущую стандартную квоту, стоимость методов и порядок запроса дополнительной квоты сверяйте в официальной документации: Quota and Compliance Audits и Quota Calculator. Значения и процедуры могут меняться.

2. Ограничение загрузок канала

Причина uploadLimitExceeded относится не к бюджету API-проекта, а к возможности конкретного пользователя или канала загружать видео. В официальном справочнике ошибок метода videos.insert она описана как превышение количества видео, которое пользователь может загрузить.

Это различие легко проверить: другие методы API могут работать, квота проекта остаётся доступной, а загрузка видео в один канал отклоняется. Другой канал в том же проекте при этом может не иметь такой ошибки.

YouTube не публикует единое гарантированное количество загрузок, подходящее каждому каналу. Не планируйте систему вокруг неофициального числа и не обещайте точное время восстановления, если его нет в ответе или официальной справке. На доступность функций канала могут влиять история канала, подтверждение, нарушения и другие сигналы платформы.

Для текущего описания причины используйте официальный раздел Errors for videos.insert. Более широкое объяснение этой ошибки есть в статье о лимите загрузок YouTube, но фактические значения всегда сверяйте с официальными источниками.

3. Авторизация и права

Ошибки OAuth часто выглядят для пользователя как «API больше не даёт загрузить», хотя квота здесь ни при чём. Типичные признаки: HTTP 401, authError, invalidCredentials, истёкший или отозванный токен, неправильный OAuth-клиент либо отсутствие нужной области доступа.

HTTP 403 тоже не всегда означает квоту. Он может указывать на недостаточные права, запрет операции для канала, несоответствие владельца токена каналу или другую проверку доступа.

Проверьте:

• какой пользователь выдал разрешение;
• к какому YouTube-каналу относится авторизация;
• запрошена ли подходящая OAuth scope для операции;
• не был ли доступ отозван в настройках Google Account;
• умеет ли приложение обновлять access token;
• использует ли сервер актуальный OAuth client ID и redirect URI;
• не выводятся ли токены в логи.

Не «лечите» авторизацию сменой API key. Загрузка от имени пользователя требует OAuth 2.0. Также не просите пользователя прислать access token в поддержку. Достаточно времени ошибки, причины, идентификатора запроса и обезличенных сведений о конфигурации.

4. Некорректный запрос или состояние ресурса

HTTP 400 и некоторые ответы 403 возникают из-за самого запроса. Причиной может быть обязательный параметр, недопустимое значение, неподдерживаемая комбинация полей, неверная категория, неправильный формат метаданных или операция, запрещённая для текущего состояния ресурса.

Для resumable upload ошибка может появиться на разных этапах: при создании сессии, передаче байтов или завершении обработки. Сохраняйте этап и заголовки ответа. Не запускайте новую загрузку автоматически после любого тайм-аута: сначала выясните, не принял ли YouTube предыдущую попытку. Иначе приложение создаст дубликаты.

Сверяйте запрос со справочником конкретного метода, а не с общим списком ошибок. Для загрузки это документация videos.insert, для других операций — страница соответствующего ресурса и метода.

Диагностический чек-лист

Шаг 1. Сохраните исходный ответ

Запишите HTTP-статус, верхнеуровневое сообщение, domain, reason, метод, endpoint, время с часовым поясом и request ID, если он доступен. Удалите из логов OAuth-токены, cookies и персональные данные.

Пример полезной записи:

2026-08-11T14:05:22Z
method: youtube.videos.insert
status: 403
reason: uploadLimitExceeded
project: production-uploader
channel: internal-id-42
upload-session: created

Такой лог гораздо полезнее строки «YouTube limit exceeded».

Шаг 2. Определите масштаб

Ответьте на три вопроса:

1. Ошибка возникает у всех пользователей проекта или у одного канала?
2. Не работает только загрузка видео или любые методы API?
3. Ошибка воспроизводится на одном файле или на любом корректном тестовом файле?

Все пользователи плюс разные методы указывают в сторону проекта или общего сбоя. Один канал плюс videos.insert — в сторону канального ограничения или прав. Один файл — в сторону файла, метаданных или обработки.

Шаг 3. Сопоставьте reason с официальным справочником

Не классифицируйте ошибку только по коду 403. Найдите точный reason на странице метода и проверьте дату документации. quotaExceeded и uploadLimitExceeded звучат похоже, но описывают разные объекты ограничения.

Если библиотека скрывает тело ответа, включите безопасное диагностическое логирование на тестовом окружении. Не записывайте заголовок Authorization.

Шаг 4. Проверьте квоту проекта

Откройте Google Cloud Console для того проекта, ключи и OAuth-клиент которого использует приложение. Сравните график потребления с временем ошибки. Разберите расход по методам и найдите повторные вызовы.

Если квота действительно закончилась, уменьшите ненужные запросы, используйте корректное кэширование там, где это допустимо, и следуйте официальной процедуре запроса дополнительной квоты. Создание новых проектов для обхода контроля не является исправлением и может нарушать требования API.

Шаг 5. Проверьте канал и OAuth

Если причина связана с загрузкой конкретного канала, откройте YouTube Studio и уведомления канала. Проверьте доступность нужных функций и предупреждения. Если причина указывает на OAuth, переподключите аккаунт через штатный flow только после проверки токена, scope и владельца канала.

Не распределяйте загрузки по чужим или запасным каналам ради обхода лимита. Загружайте только туда, где у вас есть полномочия и где публикация соответствует назначению канала.

Шаг 6. Проверьте запрос и повтор

Сравните параметры с актуальной схемой метода. Для resumable upload определите, можно ли продолжить существующую сессию. Используйте ограниченные повторы с задержкой только для временных ошибок. Для постоянных ошибок 400, ошибок прав и uploadLimitExceeded слепой retry создаёт шум, но не устраняет причину.

Шаг 7. Эскалируйте с доказательствами

В обращении укажите метод, статус, reason, время, затронутые каналы или пользователей, project ID, request ID и результаты проверок. Секреты и содержимое токенов не прикладывайте.

Быстрая таблица решений

Главное правило: число HTTP-статуса само по себе не ставит диагноз. Сначала определите точную причину и объект ограничения — проект, канал, пользователя, запрос или сессию загрузки. После этого становится понятно, где смотреть данные и какое действие действительно может помочь.