googleapis

Postconditions — what we check

• channels.list · error-api-call

  error
  WhenAsync googleapis API call (e.g., youtube.channels.list, drive.files.list, gmail.users.messages.send) is not wrapped in a try-catch block. All googleapis methods throw GaxiosError on failure.
  ThrowsGaxiosError
  Required handlingCaller MUST wrap googleapis API calls in try-catch. Check error.status for HTTP status codes: 401 → auth failure (token expired/invalid) 403 → quota exceeded or insufficient permissions 404 → resource not found 429 → rate limit exceeded 5xx → Google server error Use instanceof GaxiosError (from 'gaxios' or 'googleapis-common') for type guard.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][2]
• videos.insert · error-api-call

  error
  Whenyoutube.videos.insert() is not wrapped in a try-catch block. Throws GaxiosError on auth/quota/upload failure.
  ThrowsGaxiosError
  Required handlingCaller MUST wrap youtube.videos.insert() in try-catch. Video uploads can fail with quota errors (403), auth errors (401), or invalid request errors (400).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• files.list · error-api-call

  error
  Whendrive.files.list() not wrapped in try-catch
  ThrowsGaxiosError
  Required handlingWrap in try-catch, check error.status
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• messages.send · gmail-messages-send-auth-error

  error
  Whengmail.users.messages.send() is called without try-catch and the OAuth token is expired, invalid, or missing the gmail.send scope.
  ThrowsGaxiosError with status 401, error.code === 'authError'
  Required handlingWrap in try-catch. Check error.status === 401 and refresh the OAuth token. Verify the token has the gmail.send scope (https://mail.google.com/). Re-authenticate the user if the refresh token is also invalid.
  costhighin prodimmediate exceptionusers seelost transactionvisibilitysilent
  Sources[3]
• messages.send · gmail-messages-send-quota-exceeded

  error
  Whengmail.users.messages.send() is called without try-catch and the project or user has exhausted the Gmail API daily quota. Common in email automation services, bulk notification senders, or apps that send per-user emails without rate limiting.
  ThrowsGaxiosError with status 403, error.code === 'dailyLimitExceeded' or 'rateLimitExceeded' or 'userRateLimitExceeded'
  Required handlingWrap in try-catch. Check error.status === 403. For dailyLimitExceeded: queue messages for the next day or upgrade quota. For userRateLimitExceeded (100 requests/user/100s): implement exponential backoff and queue unsent messages. For rateLimitExceeded (project-level): use exponential backoff.
  costhighin prodsilent failureusers seelost transactionvisibilitysilent
  Sources[3]
• messages.list · gmail-messages-list-auth-error

  error
  Whengmail.users.messages.list() called without try-catch and the OAuth access token has expired. Very common in CRM integrations where tokens expire between sync cycles.
  ThrowsGaxiosError with status 401, error.code === 'authError'
  Required handlingWrap in try-catch. Check error.status === 401. Trigger OAuth token refresh flow. If refresh fails (refresh token revoked), mark the inbox connection as disconnected and notify the user.
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[3]
• messages.list · gmail-messages-list-rate-limit

  warning
  Whengmail.users.messages.list() called without try-catch and rate limit exceeded. Common when syncing large inboxes or polling too frequently.
  ThrowsGaxiosError with status 429 or 403 with rateLimitExceeded reason
  Required handlingWrap in try-catch. Implement exponential backoff for 429/403 errors. Respect the Retry-After header if present. For inbox sync use cases, use Gmail Push Notifications (watch) instead of polling.
  costlowin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[3]
• files.create · drive-files-create-storage-quota-exceeded

  error
  Whendrive.files.create() called without try-catch and the target user's Google Drive storage is full. Critical for apps that write files to user-owned drives — e.g., document export features, automated report delivery to Drive.
  ThrowsGaxiosError with status 403, error.code === 'storageQuotaExceeded'
  Required handlingWrap in try-catch. Check error.status === 403 and inspect error.response.data for 'storageQuotaExceeded'. Notify the user that their Drive storage is full. Do NOT silently retry — the operation will continue to fail until the user frees storage space.
  costmediumin prodimmediate exceptionusers seelost transactionvisibilitysilent
  Sources[4]
• files.create · drive-files-create-insufficient-permissions

  error
  Whendrive.files.create() called without try-catch when the authenticated user lacks write access to the target parent folder (Shared Drive or shared folder). Common when apps try to create files in a workspace folder the user can only read.
  ThrowsGaxiosError with status 403, error.code === 'insufficientFilePermissions'
  Required handlingWrap in try-catch. Check error.status === 403. Distinguish from quota errors by reading error.response.data.error.errors[0].reason. Display a clear permission error message — silently ignoring causes data loss.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[4]
• files.create · drive-files-create-rate-limit

  warning
  Whendrive.files.create() called in a tight loop without try-catch. Apps that upload many files in batches (e.g., bulk document generation) easily hit the Drive API rate limits (userRateLimitExceeded: 10 req/s/user).
  ThrowsGaxiosError with status 403 with rateLimitExceeded or userRateLimitExceeded reason, or status 429
  Required handlingWrap in try-catch. Implement exponential backoff for all 403 rate-limit and 429 errors. For bulk uploads, use a queue with rate limiting (e.g., p-limit, p-queue) rather than Promise.all().
  costlowin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[4]
• events.insert · calendar-events-insert-auth-error

  error
  Whencalendar.events.insert() called without try-catch and the OAuth token is expired or lacks the calendar write scope. Common in booking systems where the token expires between user authentication and event creation.
  ThrowsGaxiosError with status 401, error.code === 'authError'
  Required handlingWrap in try-catch. Check error.status === 401. Trigger OAuth token refresh. Required scope for creating events: https://www.googleapis.com/auth/calendar or https://www.googleapis.com/auth/calendar.events
  costhighin prodimmediate exceptionusers seelost transactionvisibilitysilent
  Sources[5]
• events.insert · calendar-events-insert-quota-exceeded

  warning
  Whencalendar.events.insert() called without try-catch and the project quota or per-user rate limit is exceeded. Calendar API has lower quotas than other Google APIs — 10,000 req/day/user for write operations.
  ThrowsGaxiosError with status 403, error.code === 'quotaExceeded' or 'rateLimitExceeded' or 'userRateLimitExceeded'
  Required handlingWrap in try-catch. Implement exponential backoff for 403 quota errors. For high-volume scheduling, use batched requests or the Calendar Batch API. Check error.response.data.error.errors[0].reason for exact quota type.
  costmediumin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[5]
• events.insert · calendar-events-insert-calendar-not-found

  error
  Whencalendar.events.insert() called without try-catch with a calendarId that does not exist or to which the user no longer has access. Common when a user deletes or unshares a calendar that the app stored the ID of.
  ThrowsGaxiosError with status 404, error.code === 'notFound'
  Required handlingWrap in try-catch. Check error.status === 404. Fall back to the primary calendar ('primary') or prompt the user to re-select a calendar. Do not cache calendarIds permanently — they can be deleted.
  costmediumin prodimmediate exceptionusers seelost transactionvisibilitysilent
  Sources[5]
• events.list · calendar-events-list-sync-token-invalid

  error
  Whencalendar.events.list() called without try-catch using a stored syncToken parameter for incremental sync, and the token has expired. This is a Calendar-specific behavior: syncTokens expire after roughly 6 months of inactivity or on some structural changes to the calendar.
  ThrowsGaxiosError with status 410, error.code === 'fullSyncRequired' or 'updatedMinTooLongAgo'
  Required handlingWrap in try-catch. Check error.status === 410. Discard the stored syncToken and perform a full re-sync (call events.list without syncToken to get a fresh token). Apps that use incremental sync MUST handle 410 Gone explicitly — omitting this handler causes permanent sync failure after token expiry.
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[5]
• events.list · calendar-events-list-auth-error

  error
  Whencalendar.events.list() called without try-catch and the OAuth access token has expired. Very common in background jobs that poll for calendar changes.
  ThrowsGaxiosError with status 401, error.code === 'authError'
  Required handlingWrap in try-catch. Check error.status === 401. Trigger OAuth token refresh. If the refresh token has been revoked, notify the user and mark the calendar connection as disconnected.
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[5]
• values.update · sheets-values-update-rate-limit

  warning
  Whensheets.spreadsheets.values.update() called without try-catch in a loop or rapid succession. The Sheets API enforces 60 write requests/user/min and 300 write requests/project/min. Apps that write many cells in a loop (e.g., syncing CRM data to a spreadsheet row by row) will hit this quickly.
  ThrowsGaxiosError with status 429
  Required handlingWrap in try-catch. Check error.status === 429. Use batchUpdate (writes to multiple ranges in one request) instead of repeated values.update calls. Implement exponential backoff. Per-minute quotas reset every 60 seconds.
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[6]
• values.update · sheets-values-update-not-found

  error
  Whensheets.spreadsheets.values.update() called without try-catch with a spreadsheetId or range that does not exist or is inaccessible. Common when apps store a spreadsheet ID from OAuth setup that the user later deletes or stops sharing.
  ThrowsGaxiosError with status 404
  Required handlingWrap in try-catch. Check error.status === 404. Prompt the user to reconnect their spreadsheet. Do not silently retry — the spreadsheet is gone.
  costhighin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[6]
• spreadsheets.batchUpdate · sheets-batch-update-atomic-failure

  error
  Whensheets.spreadsheets.batchUpdate() called without try-catch with a batch containing one or more invalid requests. batchUpdate is atomic: if any single sub-request fails validation or execution, the entire batch is rolled back. No partial writes occur. Common error source: invalid range notation, out-of-bounds sheet indices, or conflicting formatting requests.
  ThrowsGaxiosError with status 400, containing details of the first invalid request
  Required handlingWrap in try-catch. For 400 errors, inspect error.response.data.error.message to identify which sub-request failed. Validate all requests before submission. Consider splitting large batches to isolate failures.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[6]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]raw.githubusercontent.com/googleapis/gaxioshttps://raw.githubusercontent.com/googleapis/gaxios/main/src/common.ts
2. [2]raw.githubusercontent.com/googleapis/google-api-nodejs-clienthttps://raw.githubusercontent.com/googleapis/google-api-nodejs-client/main/README.md
3. [3]developers.google.com/gmail/apihttps://developers.google.com/gmail/api/guides/handle-errors
4. [4]developers.google.com/drive/apihttps://developers.google.com/drive/api/guides/handle-errors
5. [5]developers.google.com/calendar/apihttps://developers.google.com/calendar/api/guides/errors
6. [6]developers.google.com/sheets/apihttps://developers.google.com/sheets/api/limits