# 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.

Source: https://voxgig.com/howto/decide-which-status-codes-an-sdk-retries

- Audience: library-maintainer
- Level: intermediate
- Verified: 2026-11-21
- Published: 2026-11-21

## 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](/howto/read-ratelimit-headers-and-pace-before-429).

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [go-retryablehttp DefaultRetryPolicy](https://pkg.go.dev/github.com/hashicorp/go-retryablehttp) | Any Go client that takes an `*http.Client`, generated or not | Retries 505 and every 5xx but 501, and skips 408 and `x-should-retry` | Your table differs from it, so write a `CheckRetry` |
| [oapi-codegen](https://github.com/oapi-codegen/oapi-codegen) | A Go SDK where one function can read each response's method, path and headers | Generates no retry, so you choose, add and test the library and the policy | You want retry generated into the SDK you ship |
| [`openapi-python-client`](https://github.com/openapi-generators/openapi-python-client) | A Python SDK whose callers can pass `httpx_args` | Generates no retry, and the transport you write ships outside the generated package | You want retry inside the generated client |
| [sdkgen retry feature](https://github.com/voxgig/sdkgen/blob/main/docs/reference/features.md) | One status list with one default across the TypeScript, Go and Python targets | One list per client, so a per-operation rule is a wrapper you write, and `statuses: []` differs in Python | The server must decide through a header |
| [Speakeasy x-speakeasy-retries](https://www.speakeasy.com/docs/sdks/customize/runtime/retries) | The API owner sets `statusCodes` per operation in the document, `5XX` ranges included | A vendor extension in a shared document, and an account to generate the SDK | Generation 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](https://www.stainless.com/blog/stainless-is-joining-anthropic/),
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`](https://www.speakeasy.com/docs/speakeasy-reference/cli/getting-started).
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](https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.9) 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.

```js title="table.mjs"
// 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](https://www.rfc-editor.org/rfc/rfc8470.html), 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.

```aontu title="generated/model/retry.aontu"
  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.

```bash
node matrix.mjs defaults
```

```text output
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.

```js title="sdkgen-ts.mjs"
// 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.

```bash
node per-operation.mjs
```

```text output
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](https://github.com/oapi-codegen/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.

```go title="record-go/main.go"
// 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.

```python title="record-py/retry_transport.py"
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
```

```bash
node matrix.mjs table
```

```text output
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

```bash
node --test retry.test.mjs
```

```text output
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.

```bash
node matrix.mjs empty
```

```text output
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.

## Related how-tos

- [Expose retry and timeout options in a generated SDK](/howto/expose-retry-and-timeout-options-in-an-sdk)

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

- [Read RateLimit headers and slow down before you get a 429](/howto/read-ratelimit-headers-and-pace-before-429)

- [Choose between 429 and 503 when you throttle a request](/howto/choose-429-or-503-when-throttling)

- [Inject a deterministic idempotency key generator for tests](/howto/inject-a-key-generator-into-sdk-idempotency)

## 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.

[^1]: [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.10) 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.

[^2]: The policy's [source at v0.7.8](https://github.com/hashicorp/go-retryablehttp/blob/v0.7.8/client.go)
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`](https://github.com/openai/openai-node/blob/v7.62.0/src/client.ts) 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."