# Explicit fallback

Choose which providers may receive a query and exactly when the chain may advance.

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

<a id="configure"></a>

## Configure an ordered chain

**fallback.ts · server**

```typescript
import { createSearch } from '@belweave/search-sdk';
import { context } from '@belweave/search-sdk/context';
import { tinyfish } from '@belweave/search-sdk/tinyfish';

const contextKey = process.env.CONTEXT_API_KEY;
const tinyfishKey = process.env.TINYFISH_API_KEY;
if (!contextKey || !tinyfishKey) throw new Error('Missing server credentials');

const client = createSearch({
  provider: context({ apiKey: contextKey }),
  fallback: [tinyfish({ apiKey: tinyfishKey })],
  timeoutMs: 10_000,
  attemptTimeoutMs: 4_000,
});

const response = await client.web.search({ query: 'SQLite write concurrency' });
console.log(response.provider, response.attempts, response.warnings);
```

Fallback can disclose the same query to another provider and incur additional charges. Providers are attempted sequentially in configured order. Each ID can appear only once.

<a id="advance"></a>

## When the chain advances

- `rate_limit`, `network`, `unavailable`, and `attempt_timeout` may advance to the next configured provider after any explicitly configured retries are exhausted.
- Authentication, invalid requests, unsupported options, invalid responses, caller cancellation, and the total deadline are terminal.
- An empty successful result is a success. It does not advance the chain.
- Same-provider retries are off by default. There are no hedges or quality-triggered fallback.

<a id="trace"></a>

## Inspect the trace

Every completed attempt records provider, start time, duration, and outcome. Failed attempts can include a code, HTTP status, and parsed Retry-After delay. A successful backup response adds `fallback_used`; a terminal failure exposes the complete trace on SearchError.

- [Reserve a deadline for the chain](https://searchsdk.dev/docs/reliability/timeouts)
- [Test fallback locally](https://searchsdk.dev/docs/guides/testing)