Type Alias RestTransportRetryOptions

Type declaration

• OptionalafterStatusCodes?: number[]

  The HTTP status codes allowed to retry with a Retry-After header.

  Default

  [413, 429, 503]
  Copy

• OptionalbackoffLimit?: number

  The upper limit of the delay per retry in milliseconds. To clamp the delay, set backoffLimit to 1000, for example.

  By default, the delay is calculated in the following way:

  0.3 * (2 ** (attemptCount - 1)) * 1000
  Copy

  The delay increases exponentially.

  Default

  Infinity
  Copy

• Optionaldelay?: (attemptCount: number) => number

  A function to calculate the delay between retries given attemptCount (starts from 1).

  Default

  attemptCount => 0.3 * (2 ** (attemptCount - 1)) * 1000
  Copy

• Optionaljitter?: boolean | (delay: number) => number

  Add random jitter to retry delays to prevent thundering herd problems.

  When many clients retry simultaneously (e.g., after hitting a rate limit), they can overwhelm the server again. Jitter adds randomness to break this synchronization.

  Set to true to use full jitter, which randomizes the delay between 0 and the computed delay.

  Alternatively, pass a function to implement custom jitter strategies.

  Default

  undefined (no jitter)
  Copy

  Example

  import ky from 'ky';
  
  const json = await ky('https://example.com', {
      retry: {
          limit: 5,
  
          // Full jitter (randomizes delay between 0 and computed value)
          jitter: true
  
          // Percentage jitter (80-120% of delay)
          // jitter: delay => delay * (0.8 + Math.random() * 0.4)
  
          // Absolute jitter (±100ms)
          // jitter: delay => delay + (Math.random() * 200 - 100)
      }
  }).json();
  Copy

• Optionallimit?: number

  The number of times to retry failed requests.

  Default

  2
  Copy

• OptionalmaxRetryAfter?: number

  If the Retry-After header is greater than maxRetryAfter, the request will be canceled.

  Default

  Infinity
  Copy

• Optionalmethods?: HttpMethod[]

  The HTTP methods allowed to retry.

  Default

  ['get', 'put', 'head', 'delete', 'options', 'trace']
  Copy

• OptionalretryOnTimeout?: boolean

  Whether to retry when the request times out.

  Default

  false
  Copy

  Example

  import ky from 'ky';
  
  const json = await ky('https://example.com', {
      retry: {
          limit: 3,
          retryOnTimeout: true
      }
  }).json();
  Copy

• OptionalshouldRetry?: (state: ShouldRetryState) => boolean | undefined | Promise<boolean | undefined>

  A function to determine whether a retry should be attempted.

  This function takes precedence over all other retry checks and is called first, before any other retry validation.

  Note: This is different from the beforeRetry hook:

  • shouldRetry: Controls WHETHER to retry (called before the retry decision is made)
  • beforeRetry: Called AFTER retry is confirmed, allowing you to modify the request

  Should return:

  • true to force a retry (bypasses retryOnTimeout, status code checks, and other validations)
  • false to prevent a retry (no retry will occur)
  • undefined to use the default retry logic (retryOnTimeout, status codes, etc.)

  Example

  import ky, {HTTPError} from 'ky';
  
  const json = await ky('https://example.com', {
      retry: {
          limit: 3,
          shouldRetry: ({error, retryCount}) => {
              // Retry on specific business logic errors from API
              if (error instanceof HTTPError) {
                  const status = error.response.status;
  
                  // Retry on 429 (rate limit) but only for first 2 attempts
                  if (status === 429 && retryCount <= 2) {
                      return true;
                  }
  
                  // Don't retry on 4xx errors except rate limits
                  if (status >= 400 && status < 500) {
                      return false;
                  }
              }
  
              // Use default retry logic for other errors
              return undefined;
          }
      }
  }).json();
  Copy

• OptionalstatusCodes?: number[]

  The HTTP status codes allowed to retry.

  Default

  [408, 413, 429, 500, 502, 503, 504]
  Copy