Explicit fallback
Choose which providers may receive a query and exactly when the chain may advance.
- PrimaryAttempt the search
- Retryable failure?Advance to the next configured provider
- Next providerRecord another attempt
Success returns immediately, even with zero results. Authentication errors, cancellation, and the overall deadline stop the chain.
On this page
Configure an ordered chain
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.
When the chain advances
rate_limit,network,unavailable, andattempt_timeoutmay 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.
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.