Errors¶

All library errors derive from GoogleKitError. Site: https://ssujitx.github.io/GoogleKit/.

Official Google docs: Drive errors · Sheets errors · Calendar errors

GoogleKitError
├── ConfigurationError
│   └── MissingExtraError
├── AuthenticationError
├── AuthorizationError
│   └── InsufficientScopesError
├── APIError
│   ├── NotFoundError
│   ├── ConflictError
│   ├── RateLimitError
│   └── QuotaExceededError
├── ValidationError
├── RetryExhaustedError
├── TransportError
└── PartialFailureError

Mapping¶

HTTP/API failures from googleapiclient are mapped by map_http_error:

Status	Exception
404	`NotFoundError`
409 / 412	`ConflictError`
429	`RateLimitError` (honors `Retry-After` when present)
403 + rate-limit reasons (`userRateLimitExceeded`, `rateLimitExceeded`)	`RateLimitError`
403 + quota reason	`QuotaExceededError`
other	`APIError`

APIError preserves status_code, reason, and request_id when available. Authorization headers and tokens are never included in messages.

Retries¶

Transient failures (429, selected 403 rate limits, 5xx, and transport/timeouts) are retried per ClientConfig.retry / RetryPolicy. When attempts are exhausted, GoogleKit raises RetryExhaustedError with the original exception in last_error.

from googlekit import ClientConfig, RetryPolicy
from googlekit.gdrive import DriveClient

# Shorthand: max_attempts only
drive = DriveClient.from_oauth(
    "client_secrets.json",
    config=ClientConfig(retry=5),
)

# Full policy
drive = DriveClient.from_oauth(
    "client_secrets.json",
    config=ClientConfig(retry=RetryPolicy(max_attempts=8, initial_delay=1.0)),
)

Missing client libraries¶

from googlekit.core.exceptions import MissingExtraError

# Message includes: uv add googlekit

This only appears if Google client libraries were removed from a broken environment; they ship with the default googlekit install.

Validation¶

Local input failures raise ValidationError before a network call when practical (empty IDs, missing paths, non-positive sizes, all-day end not exclusive, etc.).

Example¶

from googlekit import GoogleKit
from googlekit.core.exceptions import GoogleKitError, NotFoundError, ValidationError

client = GoogleKit.auto(services=["gdrive"])

try:
    client.drive.files.get("missing-id")
except NotFoundError as exc:
    print(exc)
except ValidationError as exc:
    print(exc)
except GoogleKitError as exc:
    print(exc)