Production Guide
| Setting | Recommended default |
|---|---|
| Connect timeout | 3 seconds |
| Search timeout | 15 seconds |
| Document timeout | 10 seconds |
| Maximum retries | 3 |
| Backoff | Exponential with jitter, starting at 500 ms |
| Batch detail | At most 50 document_id values |
Retry only network failures and 429, 502, 503, or 504. Do not automatically retry 400, 401, or 403. For 429, wait for the greater of Retry-After and exponential backoff, then add random jitter.
Reuse HTTP connections and enforce local concurrency. Start with explicit platforms and a narrow publish-time window. Search first, use batch-get for list hydration, and fetch full content, transcripts, or snapshots only when needed.
document_id, dataset_id, source_platform, and documented enums are stable contract fields. Clients must ignore unknown response fields because Whale may add backward-compatible fields. Breaking semantic changes require a new API version and migration window.
The validation environment has no production SLA. The production hostname, SLA, and maintenance windows are supplied during commercial onboarding.