Retries

The Speakeasy SDK Generator supports the ability to generate SDKs that will automatically retry requests that fail due to network errors or any configured HTTP Status code. This can be enabled globally for all requests or on a per-request basis by using the x-speakeasy-retries extension within your OpenAPI document. The end user of the SDK can then override the default configuration by passing in a RetryConfig object to the Operation method at runtime.

Global Retries

openapi: 3.0.3
info:
  title: Swagger Petstore - OpenAPI 3.0
  version: 1.0.11
servers:
  - url: https://petstore3.swagger.io/api/v3
x-speakeasy-retries:
  strategy: backoff
  backoff:
    initialInterval: 500        # 500 milliseconds
    maxInterval: 60000          # 60 seconds
    maxElapsedTime: 3600000     # 5 minutes
    exponent: 1.5
  statusCodes:
    - 5XX
  retryConnectionErrors: true

By adding the x-speakeasy-retries extension to the root of the OpenAPI document, the SDK Generator will generate a global retry configuration that will be used for all requests made by the SDK. The x-speakeasy-retries extension supports the following properties:

Property	Type	Description	Required
`strategy`	`string`	The retry strategy to use. Currently only `backoff` is supported.	Yes
`backoff`	`object`	The configuration of the backoff strategy if chosen.	No
`backoff.initialInterval`	`integer`	The initial interval to use for the backoff strategy (in milliseconds).	No
`backoff.maxInterval`	`integer`	The maximum interval between retries (in milliseconds).	No
`backoff.maxElapsedTime`	`integer`	The maximum elapsed time to retry for (in milliseconds).	No
`backoff.exponent`	`number`	The exponent used to increase the interval between retries.	No
`statusCodes`	`array`	The HTTP Status codes to retry on.	Yes
`retryConnectionErrors`	`boolean`	Whether to retry any connection errors.	No

The statusCodes property supports passing a list of distinct HTTP Status codes to retry on, or a wildcard range to retry on; for example, 5XX will retry all Status codes between 500 (inclusive) and 600 (exclusive).

The retryConnectionErrors property will retry any network errors that occur when making the request. This includes things like DNS resolution errors, connection refused errors, etc.

The defaults for the backoff strategy are:

initialInterval: 500
maxInterval: 60000
maxElapsedTime: 3600000
exponent: 1.5

Per-request Retries

openapi: 3.0.3
info:
  title: Swagger Petstore - OpenAPI 3.0
  version: 1.0.11
servers:
  - url: https://petstore3.swagger.io/api/v3
paths:
  /pet/findByStatus:
    get:
      operationId: findPetsByStatus
      x-speakeasy-retries:
        strategy: backoff
        backoff:
          initialInterval: 500        # 500 milliseconds
          maxInterval: 60000          # 60 seconds
          maxElapsedTime: 3600000     # 5 minutes
          exponent: 1.5
        statusCodes:
          - 408
          - 500
          - 502
          - 503
        retryConnectionErrors: true
      parameters:
        - name: status
          in: query
          description: Status values that need to be considered for filter
          required: false
          explode: true
          schema:
            type: string
            default: available
            enum:
              - available
              - pending
              - sold
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'          
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
        '400':
          description: Invalid status value

Configured the same way as the global retries, the x-speakeasy-retries extension can be added to any operation to override the global retry configuration for that specific operation or add it to a specific operation if not defined globally. This can be useful if you want to retry on a different set of HTTP Status codes for a specific operation or have a different retry configuration for intervals, etc.

SDK Usage Override

Users of the SDK can override the retry strategy globally, or at the request level. This override is accomplished by providing a utils.RetryConfig object. This object supports almost the same properties as the x-speakeasy-retries extension, except for reconfiguring the status codes to retry.

Global

In order to override the retry strategy globally, initialize the SDK object with the appropriate options parameter. In all cases, if no override is provided, the retry configuration provided in the openAPI spec will be used.

In this example we are using the RetryConfig object to disable retries globally.

import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem";

s := sdk.New(sdk.WithRetryConfig(utils.RetryConfig{Strategy: "none"}))

  s = SDK(retry_config=RetryConfig(strategy='none',
    backoff=None,
    retry_connection_errors=False))

  const sdk = new SDK({retryConfig: {
    strategy: "none",
    retryConnectionErrors: false,
  }});

Request Level Override

Any endpoints that support retries allow retry configuration override. In go, that is accomplished with an operations.WithRetries option. In python and typescript, an optional retries is accepted.

s := sdk.New()
s.FindPetsByStatus(&operations.FindPetsByStatusRequest{},
  operations.WithRetries(utils.RetryConfig{
    Strategy: "backoff",
    Backoff: &utils.BackoffStrategy{
      InitialInterval: 100,
      MaxInterval: 10000,
      MaxElapsedTime: 60000,
      Exponent: 1.1,
    },
    RetryConnectionErrors: false,
  },
)

  s = sdk()
  res = s.find_pets_by_status(request, RetryConfig(strategy='backoff',
    backoff=BackoffStrategy(
      initial_interval=100,
      max_interval=10000,
      exponent=1.1,
      max_elapsed_time=60000),
    retry_connection_errors=False))

  const sdk = new SDK({});
  await sdk.findPetsByStatus(request, {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,
      maxInterval: 50,
      exponent: 1.1,
      maxElapsedTime: 100,
    },
    retryConnectionErrors: false,
  });

Idempotency

If your endpoint has a defined idempotency header, the retried request will be retried with the exact idempotency key that was provided for the initial request.

paths:
  /pet:
    put:
      operationId: putPet
      x-speakeasy-retries:
        strategy: backoff
        backoff:
          initialInterval: 500        
          maxInterval: 60000          
          maxElapsedTime: 3600000     
          exponent: 1.5
        statusCodes:
          - 5XX
        retryConnectionErrors: false
      parameters:
        - name: Idempotency-Key
          schema:
            type: string
          in: header
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'  
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
          default:
            description: Error