How-to › Make calls that survive failure

How to decide which status codes an SDK should retry#

Write the retry table for an SDK you ship, set it in sdkgen, oapi-codegen and a Python client generator, and count the requests a stub sees for each status.

Audience
Library maintainer
Level
intermediate
Topic
Set retries and timeouts
Verified

Your SDK retries every 5xx, so a 501 from a method the server never implemented costs three requests and two waits before the caller sees it. It also retries 409, which recovers an update that met a lock and repeats a create the server refused as a duplicate.

What you get

You will end up with a retry table for your SDK, set in sdkgen and two other generators, and a stub run that counts the requests each status gets. This is for you if you choose an SDK’s retry defaults.

Short answer

Retry 408, 429, 502, 503 and 504, never 501 or 505, and retry 409 only on operations where your API uses it for a lock. In sdkgen, set the retry feature’s statuses list and route those operations through a second client. oapi-codegen takes the table as a go-retryablehttp CheckRetry, and openapi-python-client as an httpx2 transport. Verify by sending each status once from a stub and counting the requests.

You will need

An SDK you generate or maintain, and Node 22 or later. Verified 2026-11-21 against @voxgig/sdkgen 4.44.3, oapi-codegen v2.9.0, go-retryablehttp v0.7.8 and openapi-python-client 0.30.0. The Go and Python columns below were recorded by record.sh, which needs Go 1.26 or later and Python 3.11 or later. The document is api.json, an Orders API with a create, a load, and an update. A 429 belongs to rate limiting, covered in read RateLimit headers and slow down before you get a 429.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
go-retryablehttp DefaultRetryPolicyAny Go client that takes an *http.Client, generated or notRetries 505 and every 5xx but 501, and skips 408 and x-should-retryYour table differs from it, so write a CheckRetry
oapi-codegenA Go SDK where one function can read each response’s method, path and headersGenerates no retry, so you choose, add and test the library and the policyYou want retry generated into the SDK you ship
openapi-python-clientA Python SDK whose callers can pass httpx_argsGenerates no retry, and the transport you write ships outside the generated packageYou want retry inside the generated client
sdkgen retry featureOne status list with one default across the TypeScript, Go and Python targetsOne list per client, so a per-operation rule is a wrapper you write, and statuses: [] differs in PythonThe server must decide through a header
Speakeasy x-speakeasy-retriesThe API owner sets statusCodes per operation in the document, 5XX ranges includedA vendor extension in a shared document, and an account to generate the SDKGeneration has to run without an account

Voxgig maintains sdkgen. The rows are alphabetical, so its place is not a ranking.

Stainless has no row, because it announced on May 18, 2026 that it is winding down all hosted Stainless products, its SDK generator among them. Speakeasy is the one row where a per-operation list lives in the document, at the price of an extension other generators ignore. Its CLI also asks for an account, through speakeasy auth login. oapi-codegen and openapi-python-client let one function see the method and the headers, and leave writing it to you.

Write the table before the code

A status goes on the list when a second identical request can succeed. 408 qualifies, because RFC 9110 says a client with the request still outstanding may repeat it. 502, 503 and 504 describe a gateway or a server that is down for now. 501 and 505 describe what the server does not support, so a retry asks the same question of the same server.

// The retry table this page ships. A status not listed is returned to the caller at once.
export const RETRY = [408, 429, 502, 503, 504]

// 409 is retried only where this API uses it for a lock: the update. A duplicate create is final.
export const RETRY_409_FOR = ['update']

500 is the judgement call. A wide list keeps it, as sdkgen and go-retryablehttp do, and a crashed handler that fails the same way three times costs three requests. 425 means the server refused TLS early data, per RFC 8470, which none of the clients here was set up to send.

409 depends on the operation.1 In this API the update answers 409 while another write holds the order, and the create answers 409 for a number that exists. Only the first resolves itself.

Read the statuses sdkgen ships

The retry feature’s model file, .sdk/model/feature/retry.aontu in the scaffolded project, holds the defaults every target is generated from.

  config: {
    # Opt-in: enable per SDK via options.feature.retry.active = true
    options: {
      active: false
      retries: 2
      minDelay: 50
      maxDelay: 2000
      factor: 2
      statuses: [408, 425, 429, 500, 502, 503, 504]
    }
  }

matrix.mjs sends each status once from the stub, then a 200, and counts the requests. The TypeScript column runs live, and the other five were recorded.

node matrix.mjs defaults
default status lists, with sdkgen's retry feature switched on: requests per case (1 = not retried, 2 = retried once)
+ retryablehttp = oapi-codegen over go-retryablehttp with its DefaultRetryPolicy
                            sdkgen ts  sdkgen go  sdkgen py  oapi-codegen  + retryablehttp  openapi-python-client
400                         1          1          1          1             1                1
408                         2          2          2          1             1                1
409                         1          1          1          1             1                1
425                         2          2          2          1             1                1
429                         2          2          2          1             2                1
500                         2          2          2          1             2                1
501                         1          1          1          1             1                1
502                         2          2          2          1             2                1
503                         2          2          2          1             2                1
504                         2          2          2          1             2                1
505                         1          1          1          1             2                1
503, x-should-retry: false  2          2          2          1             2                1
400, x-should-retry: true   1          1          1          1             1                1
409 on PUT, a lock          1          1          1          1             1                1
409 on POST, a duplicate    1          1          1          1             1                1

The three sdkgen targets agree on every row. Their retry feature is off until a client sets active: true, as here. go-retryablehttp retries 505 and skips 408, because its policy is every 5xx except 501, plus 429.2 No column reads x-should-retry.

Set the table in sdkgen

The feature takes one statuses list per client and no operation name. The 409 rule therefore takes a second client for the update, or a transport wrapper passed in the client’s extend list, which sees each call’s operation.

// The retry feature takes one status list per client, so one way to give the update its 409 is a
// second client.
export function tableClients(stub) {
  const plain = client(stub, { active: true, ...FAST, statuses: RETRY })
  const with409 = client(stub, { active: true, ...FAST, statuses: [...RETRY, 409] })
  return { for: (op) => (RETRY_409_FOR.includes(op) ? with409 : plain) }
}

// Or one client, with a transport wrapper passed through `extend`. It is added after the retry
// feature, so it wraps it, and it sees each call's operation: a 409 on the update is sent once more.
export class LockRetry {
  name = 'lockretry'
  version = '0.0.1'
  active = true

  init(ctx, options) {
    const inner = ctx.utility.fetcher
    const delay = options.delay ?? 50
    ctx.utility.fetcher = async (callctx, url, fetchdef) => {
      const res = await inner(callctx, url, fetchdef)
      if (res?.status !== 409 || !RETRY_409_FOR.includes(callctx.op?.name)) return res
      await new Promise((resolve) => setTimeout(resolve, delay))
      return inner(callctx, url, fetchdef)
    }
  }
}

FAST sets minDelay: 1, maxDelay: 5 and jitter: false, which change when a retry leaves, not whether. LockRetry is enabled with feature: { lockretry: { active: true } } beside the retry feature’s options. Adding 409 to one client for every call shows the cost of the global rule.

node per-operation.mjs
statuses include 409 for every call
  update, 409 from a lock         requests 2  resolved
  create, 409 for a duplicate     requests 3  rejected
409 for the update only, through a second client
  update, 409 from a lock         requests 2  resolved
  create, 409 for a duplicate     requests 1  rejected
409 for the update only, through a wrapper in extend
  update, 409 from a lock         requests 2  resolved
  create, 409 for a duplicate     requests 1  rejected

The duplicate create met three refusals and two waits before failing.

Set the same table in the Go and Python generators

Neither generator writes retry code, and the tests search both generated clients for it. oapi-codegen’s WithHTTPClient option takes any HttpRequestDoer, so go-retryablehttp’s StandardClient() goes there, with the table as its CheckRetry. It sees the request, so the 409 rule needs no second client.

// tableRetry is the page's retry table as a go-retryablehttp CheckRetry: the server's
// x-should-retry wins, 409 is retried for the update alone, and five statuses for every call.
func tableRetry(ctx context.Context, resp *http.Response, err error) (bool, error) {
	if ctx.Err() != nil {
		return false, ctx.Err()
	}
	if err != nil {
		// No response: retry what go-retryablehttp's own policy retries, not a TLS or scheme error.
		return retryablehttp.DefaultRetryPolicy(ctx, resp, err)
	}
	switch resp.Header.Get("x-should-retry") {
	case "true":
		return true, nil
	case "false":
		return false, nil
	}
	switch resp.StatusCode {
	case 408, 429, 502, 503, 504:
		return true, nil
	case 409:
		return resp.Request.Method == http.MethodPut, nil
	}
	return false, nil
}

openapi-python-client passes httpx_args to the httpx2 client it builds, so a transport that wraps httpx2.HTTPTransport() carries the same function.

def should_retry(request: httpx2.Request, response: httpx2.Response) -> bool:
    # The server's x-should-retry wins; 409 is retried for the update (PUT) alone.
    header = response.headers.get("x-should-retry")
    if header in ("true", "false"):
        return header == "true"
    if response.status_code == 409:
        return request.method == "PUT"
    return response.status_code in RETRY
node matrix.mjs table
the page's table: retry 408, 429, 502, 503, 504, and 409 on the update
                            sdkgen ts  oapi-codegen + CheckRetry  openapi-python-client + transport
400                         1          1                          1
408                         2          2                          2
409                         1          1                          1
425                         1          1                          1
429                         2          2                          2
500                         1          1                          1
501                         1          1                          1
502                         2          2                          2
503                         2          2                          2
504                         2          2                          2
505                         1          1                          1
503, x-should-retry: false  2          1                          1
400, x-should-retry: true   1          2                          2
409 on PUT, a lock          2          2                          2
409 on POST, a duplicate    1          1                          1

The rows match until the header rows: the server can overrule the Go and Python tables, and sdkgen’s feature never reads the header. Speakeasy’s statusCodes takes codes and ranges such as 5XX on the document’s root or on one operation, and its generated SDKs respect Retry-After.

Check it worked

node --test retry.test.mjs
1..13
# tests 13
# suites 0
# pass 13
# fail 0
# cancelled 0
# skipped 0
# todo 0

The tests read the status list from retry.aontu and fail if the TypeScript SDK retries anything else. They also fail when a recorded column has a missing row or differs from the claims on this page.

When it goes wrong

A Python client retries after you switched status retries off. statuses: [] stops them in the TypeScript and Go targets, but the Python target falls back to the default list, because it reads the option with or. Set the list to a status your API never sends, such as [599]: the recorded Go and Python runs with that list retried none of the cases.

node matrix.mjs empty
statuses: [] in the retry feature
                            sdkgen ts  sdkgen go  sdkgen py
400                         1          1          1
408                         1          1          2
409                         1          1          1
425                         1          1          2
429                         1          1          2
500                         1          1          2
501                         1          1          1
502                         1          1          2
503                         1          1          2
504                         1          1          2
505                         1          1          1
503, x-should-retry: false  1          1          2
400, x-should-retry: true   1          1          1
409 on PUT, a lock          1          1          1
409 on POST, a duplicate    1          1          1

sdkgen 4.45.0, the newest release, wrote the same three retry files, so it carries the same defect.

A duplicate create takes three requests and two waits before the caller sees its 409. The cause is 409 on a global list. Move it to the operations whose 409 means a lock.

When not to do this

Do not put 409 on a global list, in any of the five rows. A conflict that is a fact about the data comes back on every retry.

Do not lean on sdkgen’s retry feature when the server must have the last word. Its feature reference says it reads Retry-After for the wait, the run shows it never reads x-should-retry, and it repeats a POST as readily as a GET. oapi-codegen with a CheckRetry is the better fit when the rule needs the method, the path and the headers in one place. Choose openapi-python-client when your callers already pass httpx2 transports, so the retry layer is one they recognize.

Do not retry 429 with this table’s backoff alone. A server that sends Retry-After has stated the wait, and the rate-limit pages cover reading it.

Last verified

Verified 2026-11-21 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3 and @voxgig/apidef 8.32.4. The Go and Python columns were recorded once with Go 1.26.0 and Python 3.13, and record.sh reproduced them byte for byte; the TypeScript column is re-run on every gate run. Speakeasy was read, not run: its options come from its retries and CLI pages, because generating with it needs an account. Every output block is what the command preceding it printed.

Footnotes

  1. RFC 9110 describes 409 as a conflict with the current state of the resource, used where the user might be able to resolve the conflict and resubmit the request. The sentence has a person in it. A retry loop resubmits without resolving anything, which works only when the conflict resolves itself, as a lock does. ↩︎ Back to text

  2. The policy’s source at v0.7.8 retries status 0 and every status from 500 up except 501. Its comment adds that this will catch invalid response codes as well, like 0 and 999. The openai package for Node, at 7.62.0, obeys x-should-retry before it looks at the status, under a comment that calls it not a standard header. It retries 409 under the comment “Retry on lock timeouts.” ↩︎ 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.