designing-sdks

Organize the SDK as a client containing resource classes with CRUD methods, following the Stripe-style resource-based pattern for APIs under 100 methods. Add a central request method handling authentication, retries with exponential backoff, and typed error conversion.

Use resource-based organization (like Stripe) for APIs under 100 methods where developer experience matters most. Choose command-based organization (like AWS SDK v3) for large APIs where bundle size and tree-shaking are critical, such as browser SDKs.

Retry only transient errors: 5xx statuses, 429 rate limits, and network timeouts. Calculate delay as base delay times 2 to the power of the attempt number, capped at a maximum, plus random jitter to prevent thundering herd.

Yes, provide both a synchronous client and an async client so users can choose based on their architecture. Python developers expect dual support, with async iterators for pagination in the async variant.

Respect the Retry-After header on 429 responses and raise a RateLimitError exposing the retry delay. Optionally track rate limit budget from response headers and pause requests proactively when the budget is exhausted.

Attach idempotency keys to mutating operations (POST, PATCH, PUT) so retries cannot create duplicate resources. Generate a UUID automatically or let callers supply their own key for operations like payment charges.