---
title: Production Guide
description: Timeouts, retries, concurrency, and compatibility requirements.
---

# 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.