Adding Retries to TypeScript v4 SDKs

TypeScript v4 SDKs now retry failed requests, and retrying is on by default. The retry client option controls how many retries are made, which status codes and methods qualify, how long each attempt may take, and how the backoff grows between attempts.

Details

By default the SDK retries up to 3 times after a dropped connection, a timed-out attempt, or a 408, 429, 500, 502, 503 or 504. The wait starts at 1 second and doubles with each retry, with up to 25% added jitter and a ceiling of 60 seconds. When the server sends a Retry-After header, the SDK waits that long instead. Each attempt has its own 60-second timeout, which bounds the attempt rather than the whole call.

Only GET, HEAD, PUT and OPTIONS are retried by default, so a POST, PATCH or DELETE is never sent twice unless you add it to httpMethodsToRetry. Every retry of a call carries the same Idempotency-Key, which makes widening the list safe for APIs that honor it. A request whose body is a stream is never retried, because a stream cannot be replayed.

A call's second argument can override maxRetries, timeout and statusCodesToRetry for that call alone. A call that exhausts its retries rejects with the last attempt's error, from the same error family as every other failure.

Usage Example

Tune the policy on the client, and override it for a single call:

import { PaymentsClient } from "payments";

const client = new PaymentsClient({
  retry: {
    maxRetries: 5,
    timeout: 10_000,
    httpMethodsToRetry: ["GET", "HEAD", "PUT", "OPTIONS", "POST"],
    onRetry: ({ attemptNumber, delay, reason }) => {
      console.warn(`retry ${attemptNumber} in ${delay}ms after a ${reason.kind}`);
    },
  },
});

// This one call is sent exactly once.
const payment = await client.payments.get({ paymentId: "pay_123" }, { retry: { maxRetries: 0 } });

Pass retry: { maxRetries: 0 } to the client to turn retrying off everywhere, for example in a test that stubs an error response.

This feature is available in the TypeScript v4 SDK. Generate it with version 2.x of the APIMatic CLI:

apimatic sdk generate --language=typescript

For the full set of flags and options, see the APIMatic CLI documentation.