«API не подключается» — слишком широкий симптом. Сохраните HTTP-статус и JSON ошибки от Google, удалив access token и ключи. Затем ответьте на один вопрос: кто делает запрос — пользователь через OAuth client или service account. Эти два режима получают доступ к файлам по-разному, и смешивание инструкций обычно создаёт новый 403.

Проверяйте самым маленьким read-only вызовом spreadsheets.get к таблице, специально расшаренной тестовому аккаунту. Если он проходит, credentials и базовый доступ исправны, а ошибку надо искать в scope записи, диапазоне или payload. Если нет — сложный экспорт пока не запускайте.

HTTP-код сокращает круг поиска

ОтветЧаще означаетСледующая улика
401 UNAUTHENTICATEDТокен отсутствует, истёк или выпущен не для этого вызоваAuthorization header и получение access token
403 PERMISSION_DENIEDНе хватает scope, API выключен или identity не имеет доступаerror.status, reason, Cloud project и sharing
404 NOT_FOUNDНеверный spreadsheetId либо файл не виден вызывающему аккаунтуID из URL и список разрешений файла
429 RESOURCE_EXHAUSTEDКвота или слишком частые запросыRetry-After, metrics и batching
400 INVALID_ARGUMENTПодключение есть, неверен range или телоПолный message и поле ошибки

Не превращайте любой 403 в просьбу «дайте редактора». Сначала прочитайте structured error: причиной может быть выключенный API или неподходящий scope. И наоборот, широкий OAuth scope не добавляет service account в ACL частной таблицы — доступ к ресурсу и разрешения токена являются разными проверками.

Identity выбирают под сценарий

  • OAuth client подходит, когда приложение работает от имени вошедшего пользователя и получает его согласие.
  • Service account представляет отдельного технического пользователя для серверной автоматизации.
  • API key не заменяет OAuth для чтения частных пользовательских таблиц.
  • Domain-wide delegation применяется только в управляемой организации и требует отдельного решения администратора.
  • Локальный quickstart и production worker должны использовать явно документированные разные credentials.

Google рекомендует выбирать минимальный scope. Например, drive.file ограничивает доступ файлами, которые приложение использует в рамках этого механизма, а spreadsheets.readonly подходит чтению таблиц. Не добавляйте полный Drive scope только ради проверки: сначала сопоставьте метод API и действительно требуемое разрешение.

Минимальный запрос фиксирует факты

GET https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}?fields=spreadsheetId,properties.title
Authorization: Bearer ACCESS_TOKEN_REDACTED

log = {
  http_status, google_error_status, google_error_reason,
  credential_type, caller_identity, cloud_project, requested_scopes
}

В журнал не попадают access token, refresh token, private key и полный credentials.json. Нужны тип credentials, email service account или внутренний ID OAuth-клиента, список scopes и проект. spreadsheetId не обязан быть секретом, но его тоже лучше маскировать в публичном тикете.

Project, API и credentials должны совпасть

В Google Cloud Console выберите проект, в котором созданы используемые credentials, и подтвердите, что Sheets API включён там же. Переменные окружения часто указывают на старый JSON от другого проекта. Запишите project_id из фактически загруженной конфигурации без private key и сравните с метриками запросов.

Доступ к таблице проверяется отдельно

Service account имеет собственный email; частная таблица не становится ему доступна только потому, что ключ действителен. Дайте тестовому техническому аккаунту минимально нужную роль на конкретный файл или используйте предусмотренную архитектуру организации. Для OAuth убедитесь, что согласие дал тот пользователь, который действительно видит таблицу.

После подключения тестируйте запись без порчи данных

  1. Прочитать title тестовой таблицы read-only методом.
  2. Прочитать маленький диапазон с известными значениями.
  3. Записать уникальный маркер в отдельный тестовый лист, если требуется write scope.
  4. Повторить запрос с просроченным токеном и проверить штатное обновление OAuth.
  5. Сымитировать 429 и убедиться в backoff без дублирования записи.
  6. Удалить тестовый маркер обычной процедурой и сохранить результаты проверки.

Для точечного разбора нужны HTTP-код, безопасная часть error JSON, тип credentials, project_id, scopes, email вызывающей identity и сведения о доступе к тестовому файлу. Сам ключ, client secret и токены передавать нельзя — они не помогают диагностике и создают инцидент безопасности.

Проверенные источники