Retries & Backoff | Clossir Docs

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:

global-retries.ts

1 import { Signum } from "@signum-tech/sdk";
2 
3 const signum = new Signum({
4   serverURL: process.env.SIGNUM_API_URL,
5   bearerAuth: process.env.SIGNUM_API_KEY,
6   retryConfig: {
7     strategy: "backoff",
8     backoff: {
9       initialInterval: 500,     // first retry after 500ms
10       maxInterval: 60_000,      // cap at 60 seconds between retries
11       exponent: 1.5,            // backoff multiplier
12       maxElapsedTime: 300_000,  // give up after 5 minutes total
13     },
14     retryConnectionErrors: true,
15   },
16 });

Per-request override

Override the retry config for a specific call:

per-request-retries.ts

1 // Disable retries for this call
2 await signum.health.getHealth({
3   retries: { strategy: "none" },
4 });
5 
6 // Use aggressive retries for a critical operation
7 await signum.attestations.postAttestations(payload, {
8   retries: {
9     strategy: "backoff",
10     backoff: {
11       initialInterval: 1000,
12       maxInterval: 30_000,
13       exponent: 2,
14       maxElapsedTime: 600_000, // wait up to 10 minutes
15     },
16   },
17 });

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

disable-retries.ts

1 const signum = new Signum({
2   serverURL: process.env.SIGNUM_API_URL,
3   bearerAuth: process.env.SIGNUM_API_KEY,
4   retryConfig: {
5     strategy: "none",
6   },
7 });

Next steps

Error Handling — catch and handle errors that survive retries
Idempotency — understand safe retry behavior for commands