Retry

Retry & Resilience

icloudpd-rs is designed to handle unreliable network conditions and transient iCloud API failures.

Error Classification

Errors are classified as transient or permanent:

Type	Examples	Retried?
Transient	HTTP 5xx, 429 (rate limit), timeouts, connection resets, checksum mismatch	Yes
Permanent	HTTP 4xx (except 429), disk I/O errors	No

Checksum mismatches are treated as transient because they typically indicate a truncated transfer or expired CDN URL, not actual data corruption.

Exponential Backoff

Retries use exponential backoff with jitter. The initial delay is configured by --retry-delay (default: 5 seconds), and doubles with each attempt:

Attempt	Approximate delay
1st retry	~5s
2nd retry	~10s
3rd retry	~20s

Random jitter is added to prevent multiple concurrent downloads from retrying at the same time. The maximum delay is capped at 60 seconds.

Two-Phase Recovery

The download pipeline has two phases:

1. Main pass — Downloads all assets with per-file retries (up to --max-retries, default: 3)
2. Cleanup pass — Re-fetches CDN URLs from iCloud for all failures, then retries them at concurrency 1

The cleanup pass addresses a common failure mode: CDN download URLs expire during long syncs. By re-fetching URLs from iCloud, the cleanup pass gets fresh URLs that are more likely to succeed. Running at concurrency 1 gives large files full bandwidth.

Timeout Strategy

File downloads use a dedicated HTTP client with no total request timeout, preventing large files from being killed mid-transfer. Stalled connections are detected via a 120s read timeout (no bytes received for 120 seconds). API calls use a separate 30s total timeout for fast failure.

API Call Retries

Retries apply not just to downloads but also to API calls:

• Album and photo enumeration
• Zone listing
• Library fetching

These use the same backoff strategy.

Download Summary

After all downloads complete, a summary is printed with:

• Total assets processed
• Successful downloads (with EXIF failure count if any occurred)
• Failed downloads
• Elapsed time

Related Flags

• --max-retries
• --retry-delay