GitbookIO/gitbook · error · Error

Search request failed: ${response.status}

Error message

Search request failed: ${response.status}

What it means

Thrown by fetchSearchResults in the GitBook search hook when the backend search endpoint returns a non-2xx HTTP status. The message embeds the raw status code (e.g. 401, 500, 503) from the response. It means the search request itself failed at the transport/HTTP level, not that zero results were found.

Source

Thrown at packages/gitbook/src/components/Search/useSearchResults.ts:348

    searchURL: string,
    scope: SearchSiteContentScope,
    query: string,
    signal?: AbortSignal,
    asEmbeddable?: boolean
): Promise<OrderedComputedResult[]> {
    const response = await fetch(searchURL, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            asEmbeddable,
            query,
            scope,
        }),
        signal,
    });

    if (!response.ok) {
        throw new Error(`Search request failed: ${response.status}`);
    }

    return response.json() as Promise<OrderedComputedResult[]>;
}

View on GitHub (pinned to db67585ee2)

Solutions

1. Check the embedded HTTP status: 401/403 → refresh or re-provision the visitor/API token; 429 → back off and retry with the Retry-After hint; 5xx → retry later or report an incident
2. Inspect the request payload (query, scope) in the network tab and confirm the scope IDs match the current site structure
3. Verify the search endpoint URL and any proxy rewrites in your dev server are forwarding cookies/headers untouched
4. If using a custom deployment, confirm the API base URL and authentication middleware are configured for the search route

Example fix

// before
const results = await fetchSearchResults(query, scope, signal);

// after
try {
    const results = await fetchSearchResults(query, scope, signal);
} catch (error) {
    if (error instanceof Error && error.message.startsWith('Search request failed:')) {
        const status = Number(error.message.split(': ')[1]);
        if (status === 429 || status >= 500) {
            // transient — surface a retry affordance instead of a hard failure
            return [];
        }
    }
    throw error;
}

const statusOk = (s?: number) => s !== undefined && s >= 200 && s < 300;

function isSearchRequestError(e: unknown): e is Error {
    return e instanceof Error && e.message.startsWith('Search request failed:');
}

try {
    const results = await fetchSearchResults(query, scope, signal);
} catch (error) {
    if (isSearchRequestError(error)) {
        const status = Number(error.message.split(': ')[1]);
        if (status === 429 || status >= 500) return []; // transient: degrade gracefully
    }
    throw error;
}

When it happens

Trigger: Calling the site search API (the fetch wrapped with signal) and the server responding with response.ok === false — e.g. expired/invalid visitor API token (401), rate limiting (429), upstream GitBook API outage (5xx), or a bad scope/space ID in the request body.

Common situations: Local dev proxy dropping the Authorization/token header, expired visitor session tokens in long-lived tabs, GitBook API incidents, or passing an incorrect scope object when building the search request.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• Failed to fetch search index: ${response.status}
• No response found
• AI Search is not enabled for this site.
• Failed to fetch OpenAPI file
• OAuth server ${endpoint} responded with ${response.status}

AI-assisted analysis of GitbookIO/gitbook@db67585ee2 (2026-08-28). Data as JSON: /api/errors/cc3eda9bc4a5685d. Report an issue: GitHub.