> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.clossir.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.clossir.com/_mcp/server.

# Retries & Backoff

GETTING STARTED · SDK · RETRIES & BACKOFF

The SDK includes built-in retry logic with exponential backoff for transient failures.
Retries are configured globally on the client and can be overridden per request.

## Default behavior

By default, the SDK retries on these status codes:

| Code  | Meaning               |
| ----- | --------------------- |
| `429` | Rate limited          |
| `500` | Internal server error |
| `502` | Bad gateway           |
| `503` | Service unavailable   |
| `504` | Gateway timeout       |

4xx errors other than 429 (client errors like 400, 401, 403, 404) are **not** retried —
they indicate a problem with the request itself.

## Global configuration

Set retry behavior when creating the client:

```ts title="global-retries.ts"
import { Signum } from "@signum-tech/sdk";

const signum = new Signum({
  serverURL: process.env.SIGNUM_API_URL,
  bearerAuth: process.env.SIGNUM_API_KEY,
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 500,     // first retry after 500ms
      maxInterval: 60_000,      // cap at 60 seconds between retries
      exponent: 1.5,            // backoff multiplier
      maxElapsedTime: 300_000,  // give up after 5 minutes total
    },
    retryConnectionErrors: true,
  },
});
```

## Per-request override

Override the retry config for a specific call:

```ts title="per-request-retries.ts"
// Disable retries for this call
await signum.health.getHealth({
  retries: { strategy: "none" },
});

// Use aggressive retries for a critical operation
await signum.attestations.postAttestations(payload, {
  retries: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1000,
      maxInterval: 30_000,
      exponent: 2,
      maxElapsedTime: 600_000, // wait up to 10 minutes
    },
  },
});
```

## Backoff strategy

The SDK uses exponential backoff with jitter:

```
delay = initialInterval × (attempt ^ exponent) + random(0, 1000ms)
```

| Parameter         | Default      | Description                    |
| ----------------- | ------------ | ------------------------------ |
| `initialInterval` | `500` ms     | Delay before the first retry   |
| `maxInterval`     | `60000` ms   | Maximum delay between retries  |
| `exponent`        | `1.5`        | Backoff multiplier per attempt |
| `maxElapsedTime`  | `3600000` ms | Total time before giving up    |

The random jitter (0-1000ms) prevents thundering herd issues when multiple clients retry
simultaneously.

## Retry-After headers

When the server returns a `Retry-After` or `Retry-After-Ms` header (common with 429
responses), the SDK respects it — the header value overrides the calculated backoff delay.

## Disabling retries

```ts title="disable-retries.ts"
const signum = new Signum({
  serverURL: process.env.SIGNUM_API_URL,
  bearerAuth: process.env.SIGNUM_API_KEY,
  retryConfig: {
    strategy: "none",
  },
});
```

## Next steps

* [Error Handling](/getting-started/sdk/error-handling) — catch and handle errors that survive retries
* [Idempotency](/getting-started/sdk/idempotency) — understand safe retry behavior for commands