api-client-designlisted

# API client design An API client is where your code meets an unreliable network and someone else's service. A good client makes the common case simple and the failure cases handled: timeouts, retries, pagination, and clear errors built in, so every caller does not reinvent them badly. ## Method 1. **Bake in timeouts and retries.** Every request has a timeout (connect and read: never infinite: see timeouts- and-retries), and retries with exponential backoff and jitter for the retryable failures (timeouts, 429, 5xx), respecting Retry-After. This logic lives in the client once, correctly, not copy-pasted into every call site where half will get it wrong (see the retry-amplification warning in timeouts-and-retries). 2. **Surface errors clearly and typed.** Map the API's errors (see api-error-responses) into meaningful, catchable types the caller can branch on (NotFoundError vs RateLimitError vs a transient network error), with the useful context (status, error code, request ID for support: see observability). A client that returns raw HTTP errors or swallows them into a generic failure pushes the error-handling burden back onto every caller. 3. **Handle pagination for the caller.** Wrap the API's pagination (see api-pagination-design) in an iterator or auto-paginating method so callers loop over items, not pages: `for order in client.orders()` fetching pages lazily underneath. Exposing raw page cursors makes every ca