«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 убедитесь, что согласие дал тот пользователь, который действительно видит таблицу.
После подключения тестируйте запись без порчи данных
- Прочитать title тестовой таблицы read-only методом.
- Прочитать маленький диапазон с известными значениями.
- Записать уникальный маркер в отдельный тестовый лист, если требуется write scope.
- Повторить запрос с просроченным токеном и проверить штатное обновление OAuth.
- Сымитировать 429 и убедиться в backoff без дублирования записи.
- Удалить тестовый маркер обычной процедурой и сохранить результаты проверки.
Для точечного разбора нужны HTTP-код, безопасная часть error JSON, тип credentials, project_id, scopes, email вызывающей identity и сведения о доступе к тестовому файлу. Сам ключ, client secret и токены передавать нельзя — они не помогают диагностике и создают инцидент безопасности.