# Retry policy

Opt into bounded retries for transient failures while preserving the complete call deadline.

Canonical: https://searchsdk.dev/docs/reliability/retries
Markdown: https://searchsdk.dev/docs/reliability/retries.md

<a id="normalized"></a>

## Normalized search retries

> **TypeScript reference**
> The API names, code and policy behavior in this article describe the TypeScript SDK. See [your language guide](https://searchsdk.dev/docs/sdks) for its supported surface and limits.

**retry.ts · fixture**

```typescript
import { createSearch } from '@belweave/search-sdk';
import { createMockProvider } from '@belweave/search-sdk/testing';

const provider = createMockProvider({ outcomes: [
  { type: 'error', code: 'rate_limit', retryAfterMs: 10 },
  { type: 'success' },
] });
const client = createSearch({
  provider,
  timeoutMs: 5_000,
  retry: { maxRetries: 1, baseDelayMs: 25, maxDelayMs: 200 },
});
const response = await client.web.search({ query: 'SQLite concurrency' });
console.log(response.attempts.length); // 2, same provider; no fallback_used

```

Additional attempts occur per provider before moving to an explicit fallback. Transient categories are `network`, `rate_limit`, `unavailable`, and `attempt_timeout`. Terminal validation, auth, caller cancellation, and total-deadline failures are not retried.

<a id="configuration"></a>

## Backoff settings

| Setting | Contract |
| --- | --- |
| `maxRetries` | Additional attempts, integer 0–5; default 0. |
| `baseDelayMs` | Positive integer starting delay; default 250. |
| `maxDelayMs` | Positive integer exponential cap; default 5,000; at least baseDelayMs. |

Backoff uses jitter and never shortens a parsed Retry-After value. If the required delay cannot fit inside the remaining deadline, the operation fails with timeout instead of retrying early. Retrying can repeat billable work.

<a id="native"></a>

## Native operations require eligibility too

A native transport retry policy alone does not make every operation replayable. The operation must explicitly declare `retryable: true`; the default is false, including for GET. Provider create/write/delete methods remain non-retrying unless their static mapping deliberately declares otherwise. There is no claim of provider idempotency.

Native retry categories are transport errors and HTTP 429, 408, or 5xx. Malformed JSON, authentication failures, and stream consumption are not retried.

- [Fallback remains separate](https://searchsdk.dev/docs/reliability/fallback)
- [Native operation inventory](https://searchsdk.dev/docs/providers)