Error Handling¶

CloudSync SDK uses a structured exception hierarchy for all error conditions.

Exception Hierarchy¶

CloudSyncError
├── AuthenticationError
│   ├── InvalidApiKeyError
│   └── KeyExpiredError
├── ConnectionError
│   ├── TimeoutError
│   ├── TransportError
│   └── ReconnectionFailedError
├── DocumentError
│   ├── DocumentNotFoundError
│   ├── DocumentTooLargeError
│   └── InvalidKeyError
├── ConflictError
├── RateLimitError
└── ServerError

Catching Errors¶

from cloudsync.exceptions import (
    CloudSyncError,
    AuthenticationError,
    ConnectionError,
    RateLimitError,
)

try:
    client.connect()
except AuthenticationError as e:
    print(f"Auth failed: {e.message} (code: {e.code})")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except ConnectionError as e:
    print(f"Connection failed: {e.message}")
except CloudSyncError as e:
    print(f"Unexpected error: {e}")

Error Object¶

All exceptions include:

Attribute	Type	Description
`code`	`str`	Machine-readable error code (e.g., `ERR_AUTH_INVALID_KEY`)
`message`	`str`	Human-readable description
`status`	`int`	HTTP-equivalent status code
`retry_after`	`float \\| None`	Seconds to wait before retrying
`request_id`	`str`	Unique ID for support requests

Error Codes¶

Code	Status	Description
`ERR_AUTH_INVALID_KEY`	401	API key is invalid or malformed
`ERR_AUTH_KEY_EXPIRED`	401	API key has been revoked or expired
`ERR_CONN_TIMEOUT`	408	Connection or request timed out
`ERR_CONN_TRANSPORT`	502	Transport-level failure
`ERR_DOC_NOT_FOUND`	404	Document key does not exist
`ERR_DOC_TOO_LARGE`	413	Document exceeds 1MB size limit
`ERR_DOC_INVALID_KEY`	400	Document key contains invalid characters
`ERR_RATE_LIMIT`	429	Too many requests
`ERR_CONFLICT`	409	Unresolvable conflict (manual strategy)
`ERR_SERVER`	500	Internal server error

Automatic Retries¶

The SDK automatically retries transient errors (timeouts, 502, 503) with exponential backoff:

client = CloudSyncClient(
    api_key="...",
    max_retries=5,           # default: 10
    retry_backoff=2.0,       # default: 1.5
    retry_max_delay=60,      # default: 120 (seconds)
)

To disable automatic retries:

client = CloudSyncClient(api_key="...", max_retries=0)

Next: Webhooks →