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
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
Hey API ky client | 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 | 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 | 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 | 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.
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.
Related how-tos
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
-
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
-
Two is the number three of these tools reached. sdkgen’s feature reference gives
retriesa default of 2, and thekyREADME giveslimitthe 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 -
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=Nonetoo. ↩︎ Back to text -
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