# How to expose retry and timeout options in a generated SDK

> Decide which retry and timeout options a generated SDK gives its users, per client and per call, and count the requests each setting sends against a local server.

Source: https://voxgig.com/howto/expose-retry-and-timeout-options-in-an-sdk

- Audience: library-maintainer
- Level: intermediate
- Languages: typescript, python, go
- Verified: 2026-11-19
- Published: 2026-11-19

## Short answer

Give users of a generated SDK a retry count and a timeout on the client, and an override for one call. sdkgen takes them as `feature: { retry: { active: true }, timeout: { active: true } }` in the constructor, with an `AbortSignal` or a second client per call. Hey API's `ky` client takes `retry` and `timeout` on the client and on each call. The Python client from `openapi-python-client` takes `timeout`, and retries need a transport you add.

---
## You will need

Node 22 or later, Python 3.11 or later for the Python section, and an OpenAPI 3 document. sdkgen's
packages declare Node 24, so npm prints `EBADENGINE` warnings on Node 22, where the scaffold and
the generation for this page both completed. The document here is `api.json`, a Courier API with
three operations on parcels. Every command runs against a stand-in server on 127.0.0.1 that
records each request before it answers.

## Approaches compared

The table lists four generators a reader can adopt.[^1]

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Hey API `ky` client](https://heyapi.dev/docs/openapi/typescript/clients/ky) | A TypeScript SDK whose users want `retry` and `timeout` on the client and on every call | Retries a status only with `throwOnError: true`, and makes `ky` a dependency of your SDK | You ship more languages than TypeScript, or your callers read `error` fields |
| [`openapi-python-client` timeout and `httpx_args`](https://github.com/openapi-generators/openapi-python-client/blob/main/openapi_python_client/templates/client.py.jinja) | A Python SDK whose users know httpx2 and want its timeout and transport types | No timeout by default, no status retry at all, and a transport you write and test | You want retries without owning a transport |
| [sdkgen retry and timeout features](https://github.com/voxgig/sdkgen/blob/main/docs/reference/features.md) | One option block with the same names in every language target you generate | No retry option per call, no method list, and both features off until a user activates them | One call needs its own retry count, or a POST must never repeat |
| [Speakeasy `x-speakeasy-retries` and `RetryConfig`](https://www.speakeasy.com/docs/sdks/customize/runtime/retries) | The API owner sets defaults per operation in the OpenAPI document, and users override per request | A vendor extension in a shared document, an account to generate, and a precedence order to document | You cannot add extensions to the document, or generation must run without an account |

Voxgig maintains sdkgen. It is one of four options here, not the recommendation.

Speakeasy is the one row that puts a default on each operation, in the document the API owner
controls, and the price is four places a policy can come from. Hey API's `ky` client gives every
call its own `retry`, but repeats nothing until the caller also sets `throwOnError`. sdkgen's
block reads the same in Go and Python, but it has no form for one call.

## Add the retry and timeout features to the project

`generate.sh` scaffolds an sdkgen project from `api.json` with both features, then generates the
TypeScript SDK.

```bash title="generate.sh"
npx --yes @voxgig/create-sdkgen@0.31.9 courier --def api.json --target ts --feature retry --feature timeout
cd courier-sdk/.sdk
npm run generate
```

The first decision is made here. A project scaffolded without `--feature retry` generates an SDK
with no retry source in it, so its users have nothing to switch on. In an existing project,
`npx voxgig-sdkgen feature add retry,timeout` in `.sdk/`, then `npm run generate`, writes the same
files. The [feature reference](https://github.com/voxgig/sdkgen/blob/main/docs/reference/features.md)
documents each option, and the generated SDK carries the table your users get.

```bash
node knobs.mjs
```

```text output
options the generated SDK declares
  retry    active=false factor=2 maxDelay=2000 minDelay=50 retries=2 statuses=[408,425,429,500,502,503,504]
           no default: jitter, sleep
  timeout  active=false ms=30000
           no default: clearTimer, now, setTimer
```

Both features stay off until a user passes `active: true`, and `retries` defaults to two.[^2] The
options without a default are for tests: `jitter: false` and an injected `sleep` make the delays
exact.

## Count the requests each constructor option sends

Each row of `knobs.mjs` builds a client with one `feature` block and makes one call against a
fresh stand-in. The last two rows pass the same two features as a map and as an ordered array.

```js title="knobs.mjs"
    ['retry and timeout, as a map', { hang: true }, list({
      retry: { active: true },
      timeout: { active: true, ms: 200 },
    })],
    ['timeout then retry, as an array', { hang: true }, list([
      { name: 'timeout', active: true, ms: 200 },
      { name: 'retry', active: true },
    ])],
```

```bash
node knobs.mjs
```

```text output
every request answered 503
  no feature option                            requests 1   request_status
  retry { active: true }                       requests 3   request_status
  retry { active: true, retries: 4 }           requests 5   request_status
  retry { active: true, retries: 0 }           requests 1   request_status
  retry { active: true }, Parcel().create()    requests 3   request_status

two 503s, then 200
  no feature option                            requests 1   request_status
  retry { active: true }                       requests 3   resolved

the server never answers
  timeout { active: true, ms: 200 }            requests 1   timeout
  retry and timeout, as a map                  requests 1   timeout
  timeout then retry, as an array              requests 3   timeout
```

`retries` counts the attempts after the first, so the default sends three requests and
`retries: 0` sends one. Say so in your README, because the name does not tell a reader whether
`retries: 2` means two requests or three.

A `create` is repeated as readily as a `list`. The feature takes no method list, and
[RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#section-9.2.2) tells a client not to retry
a POST automatically unless it knows the request is idempotent.

What the timeout covers depends on how the two features are written. As a map they are set up in
name order and the last one wraps the others, so 200 ms covers the whole retry sequence and one
request leaves. As an array with `timeout` first, each attempt gets its own 200 ms, and three
leave.

## Give one call a different policy

The generated operations take no retry count and no timeout. Their second argument is a control
object, and the one transport control it carries is `signal`. An `AbortSignal` ends one call early
and stops its retries. Switching retries off for one call takes a second client, built from the
same options.

```js title="percall.mjs"
/** The same options with retry switched off, in the map form of `feature` or the array form. */
export const withoutRetry = (options) => ({
  ...options,
  feature: Array.isArray(options.feature)
    ? options.feature.filter((entry) => entry.name !== 'retry')
    : { ...options.feature, retry: { active: false } },
})
```

```bash
node percall.mjs
```

```text output
one policy for the client: retry { active: true }, timeout { active: true, ms: 2000 }
  client.Parcel().list()                       requests 3   request_status
  a second client, retry { active: false }     requests 1   request_status
  list(undefined, { signal }), 150 ms          requests 1   request_aborted
```

The third row passed
[`AbortSignal.timeout(150)`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/timeout_static)
and failed with `request_aborted`, under a client whose own timeout was two seconds. The feature
reference documents `signal` for the TypeScript and JavaScript targets only, so in Go and Python
the second client is the whole answer. Clients built from the Go and Python targets sent one,
three, and five requests for the same three settings.

## Pass retry and timeout through the `ky` client from Hey API

Hey API writes no retry loop and no timer of its own. Each client plugin wraps an HTTP library,
and that library's options are accepted on the client and on every generated function. The
default Fetch client takes a `signal` and a replacement `fetch`. The
[`ky` client](https://heyapi.dev/docs/openapi/typescript/clients/ky) adds the `retry` and `timeout`
options of `ky`, and four lines of its generated request code decide what your users get.

```js title="heyapi/client/client.gen.js"
                throwHttpErrors: opts.throwOnError ?? false,
                ...(opts.timeout !== undefined ? { timeout: opts.timeout } : {}),
                ...opts.kyOptions,
                retry: opts.retry ?? opts.kyOptions?.retry ?? 2,
```

```bash
node heyapi.mjs
```

```text output
every request answered 503
  createClient({ baseUrl })                                  requests 1   error field, status 503
  throwOnError: true                                         requests 3   threw
  throwOnError: true, retry: { limit: 4, backoffLimit: 100 } requests 5   threw
  the same client, retry: 0 on the call                      requests 1   threw
  throwOnError: true, a createParcel                         requests 1   threw
the server never answers
  timeout: 200                                               requests 1   error field, TimeoutError
  timeout: 5000, and timeout: 150 on the call                requests 1   error field, TimeoutError
```

The first row is the one to document. A generated function returns an error instead of throwing
it, and the `ky` README says a request
[is not retried when `throwHttpErrors` is false](https://github.com/sindresorhus/ky/blob/v1.14.3/readme.md#throwhttperrors).
With the defaults a 503 is sent once, whatever `retry` says. With `throwOnError: true`, `retry` on
the client sets the count and `retry: 0` on a call switches it off for that call. A POST is not
repeated, because the default method list in `ky` leaves it out. `timeout` needs no such switch
and defaults to 10 seconds in the generated config, a figure the same README says includes any
retries.

## Add a timeout and a retrying transport to the Python client

`openapi-python-client` generates a `Client` class over httpx2. Its template documents a `timeout`
argument, a `with_timeout` method, and `httpx_args`, a dictionary passed to the HTTP client. It has
no retry option. httpx2's own
[`HTTPTransport(retries=2)`](https://pydantic.dev/docs/httpx2/advanced/transports/) repeats a
failed connection and nothing else, so retrying a status takes a transport you write.
`retry_transport.py` wraps one, for the sync and the async half of the client, and repeats
idempotent methods only.

```python title="retry_transport.py"
    def _final(self, request, response, attempt):
        return (
            attempt >= self.retries
            or request.method not in self.methods
            or response.status_code not in self.statuses
            # A body read from an iterator can be sent once: a repeat would go out empty.
            or not isinstance(request.stream, httpx2.ByteStream)
        )

    def _wait(self, attempt):
        return min(self.max_delay, self.min_delay * 2**attempt) * self.jitter()

    def handle_request(self, request):
        attempt = 0
        while True:
            response = self.inner.handle_request(request)
            if self._final(request, response, attempt):
                return response
            # Release the connection before waiting: an unread response holds it.
            response.close()
            self.sleep(self._wait(attempt))
            attempt += 1
```

```bash
PYTHONPATH=pydeps python3 pyclient.py
```

```text output
every request answered 503
  Client(base_url=url)                             requests 1   status 503
  transport=httpx2.HTTPTransport(retries=2)        requests 1   status 503
  transport=RetryTransport(retries=2)              requests 3   status 503
  transport=RetryTransport(retries=2), a create    requests 1   status 503
the server never answers
  Client(base_url=url)                             requests 1   still waiting after 1 s
  timeout=httpx2.Timeout(0.2)                      requests 1   ReadTimeout
  with_timeout(httpx2.Timeout(0.15)) on the call   requests 1   ReadTimeout
```

Read the fifth row first. httpx2
[times out after five seconds](https://pydantic.dev/docs/httpx2/advanced/timeouts/) when left
alone, but the generated `Client` passes `timeout=None`, which switches that off.[^3] A client
built from a base URL alone waits as long as the server does, so put a `timeout` in every example
you publish. `with_timeout` returns a copy for one call. It also resets the timeout of a client
that has already made a request, so build both clients before either is used.

## Check it worked

Two of the tests pin what the timeout covers, against a server that never answers.

```js title="knobs.test.mjs"
test('as a map, one timeout covers the whole retry sequence', async () => {
  const feature = { retry: { active: true }, timeout: { active: true, ms: 200 } }
  assert.deepEqual(await measure(HANG, list(feature)), { requests: 1, outcome: 'timeout' })
})

test('as an array with timeout first, each attempt gets its own deadline', async () => {
  const feature = [{ name: 'timeout', active: true, ms: 200 }, { name: 'retry', active: true }]
  assert.deepEqual(await measure(HANG, list(feature)), { requests: 3, outcome: 'timeout' })
})
```

Run the suite. It asserts every count on this page and starts the Python suite as a child process.

```bash
node --test knobs.test.mjs
```

```text output
1..21
# tests 21
# suites 0
# pass 21
# fail 0
# cancelled 0
# skipped 0
# todo 0
```

`# pass 21` with `# fail 0` means the counts hold: `1`, `3`, and `5` requests for the client
options, and `9` for the loop below.

## When it goes wrong

A user reports nine requests for one call. Their own loop of three attempts wraps a client that
sends three.

```bash
node stacked.mjs
```

```text output
a caller's own loop of 3 attempts around one list(), every request answered 503
  SDK retry off                                requests 3   request_status
  SDK retry { active: true }                   requests 9   request_status
```

RFC 9110 has a sentence for this: a client should not automatically retry a failed automatic
retry.[^4] The fix is in your README. Say on its first screen that the SDK retries, how many
times, and how to switch that off.

You edit `retries: 2` to `retries: 5` in `.sdk/model/feature/retry.aontu`, regenerate, and the SDK
still sends three requests. That file feeds the option table in the generated README and
`Config.js`. The fallback the feature uses is a literal in
`.sdk/tm/ts/src/feature/retry/RetryFeature.ts`, and each target's template holds its own. In the
run for this page, editing that literal moved the count from three to six, and
`npx voxgig-sdkgen doctor` then listed the file as customized.

## When not to do this

Do not reach for sdkgen when one call needs its own retry count, or when the API owner wants a
different policy on each operation. Its options belong to the client, and it reads no retry
extension from the document. Hey API's `ky` client gives the option on each call in TypeScript, and
Speakeasy reads defaults for each operation from the document.

Do not activate sdkgen's retry on a client that calls `create` unless the API deduplicates writes.
The feature repeats a POST as readily as a GET, and its reference pairs it with the `idempotency`
feature for that reason. A Python SDK from `openapi-python-client`, with a
transport like the one here, repeats idempotent methods only, in 84 lines your team owns.

Do not publish a timeout without saying what it covers. A deadline for the whole sequence and a
deadline for each attempt are different promises under one option name.

## Related how-tos

- [Audit SDK retry and timeout defaults before adoption](/howto/audit-sdk-retry-and-timeout-defaults)

- [Enforce one total deadline across all retry attempts](/howto/enforce-a-total-deadline-across-retry-attempts)

- [Retry fetch calls with exponential backoff in Node.js](/howto/retry-fetch-with-backoff-in-node)

- [Generate your first SDK with sdkgen](/howto/first-sdk-with-sdkgen)

- [Make PUT and DELETE safe to retry without a key](/howto/retry-put-and-delete-safely-without-a-key)

## Last verified

Verified 2026-11-19 against Node 22.23.5, Python 3.13.18, `@voxgig/create-sdkgen` 0.31.9,
`@voxgig/sdkgen` 4.44.3, `@hey-api/openapi-ts` 0.99.0, `ky` 1.14.3, `openapi-python-client` 0.30.0,
and httpx2 2.16.2. Every output block is what the command preceding it printed. sdkgen, Hey API,
and `openapi-python-client` each ran on `api.json`, and their output is committed, compiled where
it was TypeScript. sdkgen's Go and Python targets, and the edits to its model and template, ran
once and are not committed. Speakeasy was not run. Its options come from its documentation.

[^1]: The table has no row for Stainless. Its
[announcement of May 18, 2026](https://www.stainless.com/blog/stainless-is-joining-anthropic/) says
it is winding down all hosted products, the SDK generator among them. New signups, projects, and
SDKs stopped that day, and its documentation address answers with the home page.

[^2]: Two is the number three of these tools reached. sdkgen's feature reference gives `retries`
a default of 2, and the [`ky` README](https://github.com/sindresorhus/ky/blob/v1.14.3/readme.md#retry)
gives `limit` the same. Hey API writes a 2 of its own into the client it generates, ahead of that
one. None of the three says where two came from.

[^3]: The generated client imported httpx until
[version 0.30.0](https://github.com/openapi-generators/openapi-python-client/blob/main/CHANGELOG.md),
dated 2026-11-07, which files the move to httpx2 under breaking changes.
[httpx2's README](https://github.com/pydantic/httpx2) describes Pydantic picking up stewardship of
a library seeing limited activity. The line that switches the timeout off made the crossing with
it: the template for 0.29.1 passes `timeout=None` too.

[^4]: [Section 9.2.2 of RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#section-9.2.2) ends
on that sentence, one after its rule that a proxy must not automatically retry non-idempotent
requests. Both rules are written for the sender, because the sender is the only party that knows
a request is a retry.