How-to › Make calls that survive failure

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.

Audience
Library maintainer
Level
intermediate
Topic
Set retries and timeouts
Languages
TypeScript, Python and Go
Verified

A user wraps client.Parcel().list() in a loop of three attempts, because nothing in your SDK’s README says the client already retries twice. During an outage the API receives nine requests for every call they make. A second user needs one call to give up after a second, finds no option for it, and patches the generated code.

What you get

You will end up with a generated SDK whose retry and timeout options are counted against a local server, for the client and for one call, in three generators. This is for you if you ship an SDK and have to choose its defaults.

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
Hey API ky clientA TypeScript SDK whose users want retry and timeout on the client and on every callRetries a status only with throwOnError: true, and makes ky a dependency of your SDKYou ship more languages than TypeScript, or your callers read error fields
openapi-python-client timeout and httpx_argsA Python SDK whose users know httpx2 and want its timeout and transport typesNo timeout by default, no status retry at all, and a transport you write and testYou want retries without owning a transport
sdkgen retry and timeout featuresOne option block with the same names in every language target you generateNo retry option per call, no method list, and both features off until a user activates themOne call needs its own retry count, or a POST must never repeat
Speakeasy x-speakeasy-retries and RetryConfigThe API owner sets defaults per operation in the OpenAPI document, and users override per requestA vendor extension in a shared document, an account to generate, and a precedence order to documentYou 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.

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 documents each option, and the generated SDK carries the table your users get.

node knobs.mjs
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.

    ['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 },
    ])],
node knobs.mjs
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 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.

/** 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 } },
})
node percall.mjs
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) 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 adds the retry and timeout options of ky, and four lines of its generated request code decide what your users get.

                throwHttpErrors: opts.throwOnError ?? false,
                ...(opts.timeout !== undefined ? { timeout: opts.timeout } : {}),
                ...opts.kyOptions,
                retry: opts.retry ?? opts.kyOptions?.retry ?? 2,
node heyapi.mjs
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. 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) 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.

    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
PYTHONPATH=pydeps python3 pyclient.py
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 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.

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.

node --test knobs.test.mjs
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.

node stacked.mjs
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.

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.

Footnotes

  1. The table has no row for Stainless. Its announcement of May 18, 2026 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. ↩︎ Back to text

  2. Two is the number three of these tools reached. sdkgen’s feature reference gives retries a default of 2, and the ky README 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. ↩︎ Back to text

  3. The generated client imported httpx until version 0.30.0, dated 2026-11-07, which files the move to httpx2 under breaking changes. httpx2’s README 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. ↩︎ Back to text

  4. Section 9.2.2 of RFC 9110 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. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.